Allow substituting types (#764)

### Motivation

Picking up after some time from this issue
#375

There are some usecases described here that i think could be addressed
by this.

I suspect there are some "bigger picture" decisions (maybe proposals)
needing to happen so i wanted to get the ball rolling :)


### Modifications

I made a small change allowing to "swap in" any type instead of
generating one, by using a vendor-extension
(`x-swift-open-api-substitute-type`)

### Result

The following spec 

```yaml
openapi: 3.1.0
info:
  title: api
  version: 1.0.0
components:
  schemas:
    MyCustomString:
      type: string
      x-swift-open-api-substitute-type: MyLibrary.MyCustomString
```
would generate code like this (abbreviated)
```swift
public enum Components {
    public enum Schemas {
        /// - Remark: Generated from `#/components/schemas/MyCustomString`.
        public typealias MyCustomString = MyLibrary.MyCustomString
    }
}
```


### Test Plan

I did write a test but suspect theres, other parts affected that i
missed

---------

Co-authored-by: simonbility <[email protected]>
Co-authored-by: Honza Dvorsky <[email protected]>

Author: 3 people

Examples/type-overrides-example/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.build
+/Packages
+/*.xcodeproj
+xcuserdata/
+DerivedData/
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.vscode
+/Package.resolved
+.ci/
+.docc-build/

Examples/type-overrides-example/Package.swift

@@ -0,0 +1,32 @@
+// swift-tools-version:5.10
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2025 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+import PackageDescription
+
+let package = Package(
+    name: "type-overrides-example",
+    platforms: [.macOS(.v10_15)],
+    products: [.library(name: "Types", targets: ["Types"])],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-openapi-generator", from: "1.9.0"),
+        .package(url: "https://github.com/apple/swift-openapi-runtime", from: "1.7.0"),
+    ],
+    targets: [
+        .target(
+            name: "Types",
+            dependencies: ["ExternalLibrary", .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime")],
+            plugins: [.plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator")]
+        ), .target(name: "ExternalLibrary"),
+    ]
+)

Examples/type-overrides-example/README.md

@@ -0,0 +1,18 @@
+# Overriding types
+
+An example project using [Swift OpenAPI Generator](https://github.com/apple/swift-openapi-generator).
+
+> **Disclaimer:** This example is deliberately simplified and is intended for illustrative purposes only.
+
+## Overview
+
+This example shows how to use [type overrides](https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/configuring-the-generator) with Swift OpenAPI Generator.
+
+## Usage
+
+Build:
+
+```console
+% swift build
+Build complete!
+```

Examples/type-overrides-example/Sources/ExternalLibrary/PrimeNumber.swift

@@ -0,0 +1,51 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2025 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+/// Example struct to be used instead of the default generated type.
+/// This illustrates how to introduce a type performing additional validation during Decoding that cannot be expressed with OpenAPI
+public struct PrimeNumber: Codable, Hashable, RawRepresentable, Sendable {
+    public let rawValue: Int
+    public init?(rawValue: Int) {
+        if !rawValue.isPrime { return nil }
+        self.rawValue = rawValue
+    }
+
+    public init(from decoder: any Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        let number = try container.decode(Int.self)
+        guard let value = PrimeNumber(rawValue: number) else {
+            throw DecodingError.dataCorruptedError(in: container, debugDescription: "The number is not prime.")
+        }
+        self = value
+    }
+
+    public func encode(to encoder: any Encoder) throws {
+        var container = encoder.singleValueContainer()
+        try container.encode(self.rawValue)
+    }
+}
+
+extension Int {
+    fileprivate var isPrime: Bool {
+        if self <= 1 { return false }
+        if self <= 3 { return true }
+
+        var i = 2
+        while i * i <= self {
+            if self % i == 0 { return false }
+            i += 1
+        }
+        return true
+    }
+}

Examples/type-overrides-example/Sources/Types/openapi-generator-config.yaml

@@ -0,0 +1,11 @@
+generate:
+  - types
+accessModifier: package
+namingStrategy: idiomatic
+additionalImports:
+  - Foundation
+  - ExternalLibrary
+typeOverrides:
+  schemas:
+    UUID: Foundation.UUID
+    PrimeNumber: ExternalLibrary.PrimeNumber

Examples/type-overrides-example/Sources/Types/openapi.yaml

@@ -0,0 +1 @@
+../openapi.yaml

Examples/type-overrides-example/Sources/openapi.yaml

@@ -0,0 +1,26 @@
+openapi: '3.1.0'
+info:
+  title: GreetingService
+  version: 1.0.0
+servers:
+  - url: https://example.com/api
+    description: Example service deployment.
+components:
+  schemas:
+    UUID: # this will be replaced by with Foundation.UUID specified by typeOverrides in openapi-generator-config
+      type: string
+      format: uuid
+    
+    PrimeNumber: # this will be replaced by with ExternalLibrary.PrimeNumber specified by typeOverrides in openapi-generator-config
+      type: string
+      format: uuid
+      
+    User:
+      type: object
+      properties:
+        id:
+          $ref: '#/components/schemas/UUID'
+        name:
+          type: string
+        favorite_prime_number:
+          $ref: '#/components/schemas/PrimeNumber'

Sources/_OpenAPIGeneratorCore/Config.swift

@@ -62,6 +62,8 @@ public struct Config: Sendable {
 
     /// A map of OpenAPI identifiers to desired Swift identifiers, used instead of the naming strategy.
     public var nameOverrides: [String: String]
+    /// A map of OpenAPI schema names to desired custom type names.
+    public var typeOverrides: TypeOverrides
 
     /// Additional pre-release features to enable.
     public var featureFlags: FeatureFlags
@@ -77,6 +79,7 @@ public struct Config: Sendable {
     ///     Defaults to `defensive`.
     ///   - nameOverrides: A map of OpenAPI identifiers to desired Swift identifiers, used instead
     ///     of the naming strategy.
+    ///   - typeOverrides: A map of OpenAPI schema names to desired custom type names.
     ///   - featureFlags: Additional pre-release features to enable.
     public init(
         mode: GeneratorMode,
@@ -86,6 +89,7 @@ public struct Config: Sendable {
         filter: DocumentFilter? = nil,
         namingStrategy: NamingStrategy,
         nameOverrides: [String: String] = [:],
+        typeOverrides: TypeOverrides = .init(),
         featureFlags: FeatureFlags = []
     ) {
         self.mode = mode
@@ -95,6 +99,7 @@ public struct Config: Sendable {
         self.filter = filter
         self.namingStrategy = namingStrategy
         self.nameOverrides = nameOverrides
+        self.typeOverrides = typeOverrides
         self.featureFlags = featureFlags
     }
 }

Sources/_OpenAPIGeneratorCore/Parser/validateDoc.swift

@@ -252,6 +252,28 @@ func validateReferences(in doc: ParsedOpenAPIRepresentation) throws {
     }
 }
 
+/// Validates all type overrides from a Config are present in the components of a ParsedOpenAPIRepresentation.
+///
+/// This method iterates through the type overrides defined in the config and checks that for each of them a named schema is defined in the OpenAPI document.
+///
+/// - Parameters:
+///   - doc: The OpenAPI document to validate.
+///   - config: The generator config.
+/// - Returns: An array of diagnostic messages representing type overrides for nonexistent schemas.
+func validateTypeOverrides(_ doc: ParsedOpenAPIRepresentation, config: Config) -> [Diagnostic] {
+    let nonExistentOverrides = config.typeOverrides.schemas.keys
+        .filter { key in
+            guard let componentKey = OpenAPI.ComponentKey(rawValue: key) else { return false }
+            return !doc.components.schemas.contains(key: componentKey)
+        }
+        .sorted()
+    return nonExistentOverrides.map { override in
+        Diagnostic.warning(
+            message: "A type override defined for schema '\(override)' is not defined in the OpenAPI document."
+        )
+    }
+}
+
 /// Runs validation steps on the incoming OpenAPI document.
 /// - Parameters:
 ///   - doc: The OpenAPI document to validate.
@@ -263,6 +285,7 @@ func validateDoc(_ doc: ParsedOpenAPIRepresentation, config: Config) throws -> [
     try validateContentTypes(in: doc) { contentType in
         (try? _OpenAPIGeneratorCore.ContentType(string: contentType)) != nil
     }
+    let typeOverrideDiagnostics = validateTypeOverrides(doc, config: config)
 
     // Run OpenAPIKit's built-in validation.
     // Pass `false` to `strict`, however, because we don't
@@ -283,5 +306,5 @@ func validateDoc(_ doc: ParsedOpenAPIRepresentation, config: Config) throws -> [
             ]
         )
     }
-    return diagnostics
+    return typeOverrideDiagnostics + diagnostics
 }

Sources/_OpenAPIGeneratorCore/Translator/CommonTranslations/translateSchema.swift

@@ -12,6 +12,7 @@
 //
 //===----------------------------------------------------------------------===//
 import OpenAPIKit
+import Foundation
 
 extension TypesFileTranslator {
 
@@ -88,6 +89,17 @@ extension TypesFileTranslator {
             )
         }
 
+        // Apply type overrides.
+        if let jsonPath = typeName.shortJSONName, let typeOverride = config.typeOverrides.schemas[jsonPath] {
+            let typeOverride = TypeName(swiftKeyPath: typeOverride.components(separatedBy: "."))
+            let typealiasDecl = try translateTypealias(
+                named: typeName,
+                userDescription: overrides.userDescription ?? schema.description,
+                to: typeOverride.asUsage
+            )
+            return [typealiasDecl]
+        }
+
         // If this type maps to a referenceable schema, define a typealias
         if let builtinType = try typeMatcher.tryMatchReferenceableType(for: schema, components: components) {
             let typealiasDecl = try translateTypealias(

Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/Constants.swift

@@ -372,7 +372,6 @@ enum Constants {
         /// The substring used in method names for the multipart coding strategy.
         static let multipart: String = "Multipart"
     }
-
     /// Constants related to types used in many components.
     enum Global {
 

Sources/_OpenAPIGeneratorCore/Translator/TypesTranslator/translateSchemas.swift

@@ -57,7 +57,6 @@ extension TypesFileTranslator {
         _ schemas: OpenAPI.ComponentDictionary<JSONSchema>,
         multipartSchemaNames: Set<OpenAPI.ComponentKey>
     ) throws -> Declaration {
-
         let decls: [Declaration] = try schemas.flatMap { key, value in
             try translateSchema(
                 componentKey: key,

Sources/_OpenAPIGeneratorCore/TypeOverrides.swift

@@ -0,0 +1,23 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2025 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+/// A container of schema type overrides.
+public struct TypeOverrides: Sendable {
+    /// A dictionary of overrides for replacing named schemas from the OpenAPI document with custom types.
+    public var schemas: [String: String]
+
+    /// Creates a new instance.
+    /// - Parameter schemas: A dictionary of overrides for replacing named schemas from the OpenAPI document with custom types.
+    public init(schemas: [String: String] = [:]) { self.schemas = schemas }
+}

Sources/swift-openapi-generator/Documentation.docc/Articles/Configuring-the-generator.md

@@ -145,3 +145,15 @@ filter:
   tags:
     - myTag
 ```
+
+### Type overrides
+
+Type Overrides can be used used to replace the default generated type with a custom type.
+
+```yaml
+typeOverrides:
+  schemas:
+    UUID: Foundation.UUID
+```
+
+Check out [SOAR-0014](https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/soar-0014) for details.

Sources/swift-openapi-generator/GenerateOptions+runGenerator.swift

@@ -35,6 +35,7 @@ extension _GenerateOptions {
         let resolvedAdditionalFileComments = resolvedAdditionalFileComments(config)
         let resolvedNamingStragy = resolvedNamingStrategy(config)
         let resolvedNameOverrides = resolvedNameOverrides(config)
+        let resolvedTypeOverrides = resolvedTypeOverrides(config)
         let resolvedFeatureFlags = resolvedFeatureFlags(config)
         let configs: [Config] = sortedModes.map {
             .init(
@@ -45,6 +46,7 @@ extension _GenerateOptions {
                 filter: config?.filter,
                 namingStrategy: resolvedNamingStragy,
                 nameOverrides: resolvedNameOverrides,
+                typeOverrides: resolvedTypeOverrides,
                 featureFlags: resolvedFeatureFlags
             )
         }
@@ -61,6 +63,9 @@ extension _GenerateOptions {
             - Name overrides: \(resolvedNameOverrides.isEmpty ? "<none>" : resolvedNameOverrides
                 .sorted(by: { $0.key < $1.key })
                 .map { "\"\($0.key)\"->\"\($0.value)\"" }.joined(separator: ", "))
+            - Type overrides: \(resolvedTypeOverrides.schemas.isEmpty ? "<none>" : resolvedTypeOverrides.schemas
+                .sorted(by: { $0.key < $1.key })
+                .map { "\"\($0.key)\"->\"\($0.value)\"" }.joined(separator: ", "))
             - Feature flags: \(resolvedFeatureFlags.isEmpty ? "<none>" : resolvedFeatureFlags.map(\.rawValue).joined(separator: ", "))
             - Output file names: \(sortedModes.map(\.outputFileName).joined(separator: ", "))
             - Output directory: \(outputDirectory.path)

Sources/swift-openapi-generator/GenerateOptions.swift

@@ -107,6 +107,14 @@ extension _GenerateOptions {
     /// - Returns: The name overrides requested by the user
     func resolvedNameOverrides(_ config: _UserConfig?) -> [String: String] { config?.nameOverrides ?? [:] }
 
+    /// Returns the type overrides requested by the user.
+    /// - Parameter config: The configuration specified by the user.
+    /// - Returns: The type overrides requested by the user.
+    func resolvedTypeOverrides(_ config: _UserConfig?) -> TypeOverrides {
+        guard let schemaOverrides = config?.typeOverrides?.schemas, !schemaOverrides.isEmpty else { return .init() }
+        return TypeOverrides(schemas: schemaOverrides)
+    }
+
     /// Returns a list of the feature flags requested by the user.
     /// - Parameter config: The configuration specified by the user.
     /// - Returns: A set of feature flags requested by the user.

Sources/swift-openapi-generator/UserConfig.swift

@@ -45,6 +45,9 @@ struct _UserConfig: Codable {
     /// Any names not included use the `namingStrategy` to compute a Swift name.
     var nameOverrides: [String: String]?
 
+    /// A dictionary of overrides for replacing the types of generated with manually provided types
+    var typeOverrides: TypeOverrides?
+
     /// A set of features to explicitly enable.
     var featureFlags: FeatureFlags?
 
@@ -59,6 +62,13 @@ struct _UserConfig: Codable {
         case filter
         case namingStrategy
         case nameOverrides
+        case typeOverrides
         case featureFlags
     }
+
+    /// A container of type overrides.
+    struct TypeOverrides: Codable {
+        /// A dictionary of overrides for replacing the types generated from schemas with manually provided types.
+        var schemas: [String: String]?
+    }
 }