WIP Proposal

Author: simonbility

Sources/swift-openapi-generator/Documentation.docc/Proposals/Proposals.md

@@ -55,3 +55,4 @@ If you have any questions, tag [Honza Dvorsky](https://github.com/czechboy0) or
 - <doc:SOAR-0011>
 - <doc:SOAR-0012>
 - <doc:SOAR-0013>
+- <doc:SOAR-0014>

Sources/swift-openapi-generator/Documentation.docc/Proposals/SOAR-0014.md

@@ -0,0 +1,72 @@
+# SOAR-0014: Support Type Substitutions
+
+Allow using user-defined types instead of generated ones, utilizing vendor-extensions
+
+## Overview
+
+- Proposal: SOAR-0014
+- Author(s): [simonbility](https://github.com/simonbility)
+- Status: **Awaiting Review**
+- Issue: [apple/swift-openapi-generator#375](https://github.com/apple/swift-openapi-generator/issues/375)
+- Implementation:
+    - [apple/swift-openapi-generator#764](https://github.com/apple/swift-openapi-generator/pull/764)
+- Affected components:
+    - generator
+
+### Introduction
+
+The goal of this proposal is to allow users to specify custom types for generated code using vendor extensions. This will enable users to use their own types instead of the default generated ones, allowing for greater flexibility.
+
+### Motivation
+
+This proposal would enable more flexibility in the generated code.
+Some usecases include:
+- Using custom types that are already defined in the user's codebase or even coming from a third party library, instead of generating new ones.
+- workaround missing support for `format`
+- Implement custom validation/encoding/decoding logic that cannot be expressed using the OpenAPI spec
+
+This is intended as a "escape hatch" for use-cases that (currently) cannot be expressed.
+Using this comes with the risk of user-provided types not being compliant with the original OpenAPI spec.
+
+
+### Proposed solution
+
+The proposed solution is to allow the `x-swift-open-api-replace-type` vendor-extension to prevent the generation of types as usual, and instead use the specified type.
+This should be supported anywhere within a OpenAPI document where a schema can be defined.
+This includes:
+* "TopLevel" schemas in `components.schemas`
+* "Inline" schema definitions in object
+
+```diff
+
+
+```
+
+
+Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds.
+
+This section should focus on what will change for the _adopters_ of Swift OpenAPI Generator.
+
+### Detailed design
+
+Describe the implementation of the feature, a link to a prototype implementation is encouraged here.
+
+This section should focus on what will change for the _contributors_ to Swift OpenAPI Generator.
+
+### API stability
+
+Discuss the API implications, making sure to considering all of:
+- runtime public API
+- runtime "Generated" SPI
+- existing transport and middleware implementations
+- generator implementation affected by runtime API changes
+- generator API (config file, CLI, plugin)
+- existing and new generated adopter code
+
+### Future directions
+
+Discuss any potential future improvements to the feature.
+
+### Alternatives considered
+
+Discuss the alternative solutions considered, even during the review process itself.