Create an Unresolved* typealias for all supported OpenAPI types (apple#74)

### Motivation

Currently, when referencing OpenAPI types that may not be referenceable,
it requires a very long and unintuitive type name (e.g.,
`Either<JSONReference<OpenAPI.Request>, OpenAPI.Request>`). We can clean
this up, by exposing more usable, and practical typealiases to improve
quality of life and speed while working on the generator.

### Modifications

**Added and used `Unresolved*` typaliases for:**
- OpenAPI.Request
- OpenAPI.Response
- OpenAPI.Header
- JSONSchema

### Result

New typealiases will be added, decreasing confusion, and increasing
symmetry when using OpenAPI types.

### Resolves

Resolves apple#12 

### Edits

1. Removed additions of `Resolved*` typealiases

---------

Co-authored-by: andrewelliott <>
Co-authored-by: Si Beaumont <[email protected]>

Author: andrewse02

Sources/_OpenAPIGeneratorCore/Translator/CommonTranslations/translateSchema.swift

@@ -30,7 +30,7 @@ extension FileTranslator {
     ///   instead of extracted from the schema.
     func translateSchema(
         typeName: TypeName,
-        schema: Either<JSONReference<JSONSchema>, JSONSchema>?,
+        schema: UnresolvedSchema?,
         overrides: SchemaOverrides
     ) throws -> [Declaration] {
         let unwrappedSchema: JSONSchema

Sources/_OpenAPIGeneratorCore/Translator/Content/SchemaContent.swift

@@ -24,7 +24,7 @@ struct SchemaContent {
     ///
     /// Can be nil for unstructured JSON payloads, or for unstructured
     /// content types such as binary data.
-    var schema: Either<JSONReference<JSONSchema>, JSONSchema>?
+    var schema: UnresolvedSchema?
 }
 
 /// A type grouping schema content and its computed Swift type usage.
@@ -44,3 +44,8 @@ struct TypedSchemaContent {
         typeUsage ?? TypeName.valueContainer.asUsage
     }
 }
+
+/// An unresolved OpenAPI schema.
+///
+/// Can be either a reference or an inline schema.
+typealias UnresolvedSchema = Either<JSONReference<JSONSchema>, JSONSchema>

Sources/_OpenAPIGeneratorCore/Translator/Operations/OperationDescription.swift

@@ -138,7 +138,7 @@ extension OperationDescription {
     /// Returns all parameters by resolving any parameter references first.
     ///
     /// - Throws: When an invalid JSON reference is found.
-    var allResolvedParameters: [ResolvedParameter] {
+    var allResolvedParameters: [OpenAPI.Parameter] {
         get throws {
             try allParameters.map { try $0.resolve(in: components) }
         }

Sources/_OpenAPIGeneratorCore/Translator/Parameters/TypedParameter.swift

@@ -20,7 +20,7 @@ struct TypedParameter {
     var parameter: OpenAPI.Parameter
 
     /// The underlying schema.
-    var schema: Either<JSONReference<JSONSchema>, JSONSchema>
+    var schema: UnresolvedSchema
 
     /// The computed type usage.
     var typeUsage: TypeUsage
@@ -66,7 +66,7 @@ extension TypedParameter {
     }
 }
 
-extension Either where A == JSONReference<JSONSchema>, B == JSONSchema {
+extension UnresolvedSchema {
 
     /// A schema to be inlined.
     ///
@@ -128,7 +128,7 @@ extension FileTranslator {
         let locationTypeName = parameter.location.typeName(in: parent)
         let foundIn = "\(locationTypeName.description)/\(parameter.name)"
 
-        let schema: Either<JSONReference<JSONSchema>, JSONSchema>
+        let schema: UnresolvedSchema
         let codingStrategy: CodingStrategy
         switch parameter.schemaOrContent {
         case let .a(schemaContext):
@@ -228,9 +228,6 @@ extension FileTranslator {
 /// Can be either a reference or an inline parameter.
 typealias UnresolvedParameter = Either<JSONReference<OpenAPI.Parameter>, OpenAPI.Parameter>
 
-/// A resolved OpenAPI parameter.
-typealias ResolvedParameter = OpenAPI.Parameter
-
 extension OpenAPI.Parameter.Context.Location {
 
     /// A name of the location usable as a Swift type name.

Sources/_OpenAPIGeneratorCore/Translator/RequestBody/TypedRequestBody.swift

@@ -55,7 +55,7 @@ extension FileTranslator {
     /// - Returns: Typed request content; nil if the request body is
     /// unsupported.
     func typedRequestBody(
-        from unresolvedRequest: Either<JSONReference<OpenAPI.Request>, OpenAPI.Request>,
+        from unresolvedRequest: UnresolvedRequest,
         inParent parent: TypeName
     ) throws -> TypedRequestBody? {
         let type: TypeName
@@ -81,7 +81,7 @@ extension FileTranslator {
     /// unsupported.
     func typedRequestBody(
         typeName: TypeName,
-        from unresolvedRequest: Either<JSONReference<OpenAPI.Request>, OpenAPI.Request>
+        from unresolvedRequest: UnresolvedRequest
     ) throws -> TypedRequestBody? {
 
         let request: OpenAPI.Request
@@ -113,3 +113,8 @@ extension FileTranslator {
         )
     }
 }
+
+/// An unresolved OpenAPI request.
+///
+/// Can be either a reference or an inline request.
+typealias UnresolvedRequest = Either<JSONReference<OpenAPI.Request>, OpenAPI.Request>

Sources/_OpenAPIGeneratorCore/Translator/RequestBody/translateRequestBody.swift

@@ -76,7 +76,7 @@ extension TypesFileTranslator {
     ///   - unresolvedRequestBody: An unresolved request body.
     ///   - parent: The type name of the parent structure.
     func parseRequestBodyAsProperty(
-        for unresolvedRequestBody: Either<JSONReference<OpenAPI.Request>, OpenAPI.Request>?,
+        for unresolvedRequestBody: UnresolvedRequest?,
         inParent parent: TypeName
     ) throws -> PropertyBlueprint {
         let bodyEnumTypeName: TypeName

Sources/_OpenAPIGeneratorCore/Translator/Responses/TypedResponse.swift

@@ -59,3 +59,8 @@ extension FileTranslator {
         )
     }
 }
+
+/// An unresolved OpenAPI response.
+///
+/// Can be either a reference or an inline response.
+typealias UnresolvedResponse = Either<JSONReference<OpenAPI.Response>, OpenAPI.Response>

Sources/_OpenAPIGeneratorCore/Translator/Responses/TypedResponseHeader.swift

@@ -24,7 +24,7 @@ struct TypedResponseHeader {
     var name: String
 
     /// The underlying schema.
-    var schema: Either<JSONReference<JSONSchema>, JSONSchema>
+    var schema: UnresolvedSchema
 
     /// The Swift type representing the response header.
     var typeUsage: TypeUsage
@@ -87,7 +87,7 @@ extension FileTranslator {
     ///   - parent: The Swift type name of the parent type of the headers.
     /// - Returns: Typed response header if supported, nil otherwise.
     func typedResponseHeader(
-        from unresolvedHeader: Either<JSONReference<OpenAPI.Header>, OpenAPI.Header>,
+        from unresolvedHeader: UnresolvedHeader,
         named name: String,
         inParent parent: TypeName
     ) throws -> TypedResponseHeader? {
@@ -103,7 +103,7 @@ extension FileTranslator {
 
         let foundIn = "\(parent.description)/\(name)"
 
-        let schema: Either<JSONReference<JSONSchema>, JSONSchema>
+        let schema: UnresolvedSchema
         let codingStrategy: CodingStrategy
 
         switch header.schemaOrContent {
@@ -164,3 +164,8 @@ extension FileTranslator {
         )
     }
 }
+
+/// An unresolved OpenAPI response header.
+///
+/// Can be either a reference or an inline response header.
+typealias UnresolvedHeader = Either<JSONReference<OpenAPI.Header>, OpenAPI.Header>

Sources/_OpenAPIGeneratorCore/Translator/TypeAssignment/TypeAssigner.swift

@@ -73,7 +73,7 @@ struct TypeAssigner {
     /// - Returns: A type usage; or nil if the schema is nil or unsupported.
     static func typeUsage(
         usingNamingHint hint: String,
-        withSchema schema: Either<JSONReference<JSONSchema>, JSONSchema>?,
+        withSchema schema: UnresolvedSchema?,
         inParent parent: TypeName
     ) throws -> TypeUsage? {
         let associatedType: TypeUsage?

Sources/_OpenAPIGeneratorCore/Translator/TypeAssignment/TypeMatcher.swift

@@ -125,7 +125,7 @@ struct TypeMatcher {
     /// - Parameter schema: The schema to match a referenceable type for.
     /// - Returns: `true` if the schema is referenceable; `false` otherwise.
     static func isReferenceable(
-        _ schema: Either<JSONReference<JSONSchema>, JSONSchema>?
+        _ schema: UnresolvedSchema?
     ) -> Bool {
         guard let schema else {
             // fragment type is referenceable
@@ -163,7 +163,7 @@ struct TypeMatcher {
     /// - Parameter schema: The schema to match a referenceable type for.
     /// - Returns: `true` if the schema is inlinable; `false` otherwise.
     static func isInlinable(
-        _ schema: Either<JSONReference<JSONSchema>, JSONSchema>?
+        _ schema: UnresolvedSchema?
     ) -> Bool {
         !isReferenceable(schema)
     }

Sources/_OpenAPIGeneratorCore/Translator/TypeAssignment/isSchemaSupported.swift

@@ -41,7 +41,7 @@ extension FileTranslator {
     ///   - foundIn: A description of the schema's context.
     /// - Returns: `true` if the schema is supported; `false` otherwise.
     func validateSchemaIsSupported(
-        _ schema: Either<JSONReference<JSONSchema>, JSONSchema>?,
+        _ schema: UnresolvedSchema?,
         foundIn: String
     ) throws -> Bool {
         guard try isSchemaSupported(schema) else {
@@ -116,7 +116,7 @@ extension FileTranslator {
     ///   - schema: The schema to validate.
     /// - Returns: `true` if the schema is supported; `false` otherwise.
     func isSchemaSupported(
-        _ schema: Either<JSONReference<JSONSchema>, JSONSchema>?
+        _ schema: UnresolvedSchema?
     ) throws -> Bool {
         guard let schema else {
             // fragment type is supported