Allow substituting types

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,39 @@
+// swift-tools-version:5.10
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2024 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(.v14)],
+    products: [
+        .library(name: "Types", targets: ["Types"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-openapi-generator", from: "1.6.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 the TypeOverrides feature of the Swift OpenAPI Generator.
+
+## Usage
+
+Build:
+
+```console
+% swift build
+Build complete!
+```

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

@@ -0,0 +1,38 @@
+
+/// 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,46 @@
+openapi: '3.1.0'
+info:
+  title: GreetingService
+  version: 1.0.0
+servers:
+  - url: https://example.com/api
+    description: Example service deployment.
+paths:
+  /user:
+    get:
+      operationId: getUser
+      parameters:
+        - name: name
+          required: false
+          in: query
+          description: The name of the user
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A success response with the user.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+components:
+  schemas:
+    UUID: # this will be replaced by with Foundation.UUID specified by typeOverrides in open-api-generator-config
+      type: string
+      format: uuid
+
+    PrimeNumber: # this will be replaced by with ExternalLibrary.PrimeNumber specified by typeOverrides in open-api-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

@@ -59,6 +59,9 @@ 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 paths to desired Types
+    public var typeOverrides: TypeOverrides
 
     /// Additional pre-release features to enable.
     public var featureFlags: FeatureFlags
@@ -73,6 +76,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 paths to desired Types
     ///   - featureFlags: Additional pre-release features to enable.
     public init(
         mode: GeneratorMode,
@@ -81,6 +85,7 @@ public struct Config: Sendable {
         filter: DocumentFilter? = nil,
         namingStrategy: NamingStrategy,
         nameOverrides: [String: String] = [:],
+        typeOverrides: TypeOverrides = TypeOverrides(),
         featureFlags: FeatureFlags = []
     ) {
         self.mode = mode
@@ -89,6 +94,7 @@ public struct Config: Sendable {
         self.filter = filter
         self.namingStrategy = namingStrategy
         self.nameOverrides = nameOverrides
+        self.typeOverrides = typeOverrides
         self.featureFlags = featureFlags
     }
 }

Sources/_OpenAPIGeneratorCore/Translator/CommonTranslations/translateSchema.swift

@@ -12,6 +12,7 @@
 //
 //===----------------------------------------------------------------------===//
 import OpenAPIKit
+import Foundation
 
 extension TypesFileTranslator {
 
@@ -87,6 +88,15 @@ extension TypesFileTranslator {
                 )
             )
         }
+        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) {

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,6 +57,7 @@ extension TypesFileTranslator {
         _ schemas: OpenAPI.ComponentDictionary<JSONSchema>,
         multipartSchemaNames: Set<OpenAPI.ComponentKey>
     ) throws -> Declaration {
+        try diagnoseTypeOverrideForNonExistentSchema()
 
         let decls: [Declaration] = try schemas.flatMap { key, value in
             try translateSchema(
@@ -76,4 +77,18 @@ extension TypesFileTranslator {
         )
         return componentsSchemasEnum
     }
+    private func diagnoseTypeOverrideForNonExistentSchema() throws {
+        let nonExistentOverrides = config.typeOverrides.schemas.keys
+            .filter { key in
+                guard let componentKey = OpenAPI.ComponentKey(rawValue: key) else { return false }
+                return !self.components.schemas.contains(key: componentKey)
+            }
+            .sorted()
+
+        for override in nonExistentOverrides {
+            try diagnostics.emit(
+                .warning(message: "TypeOverride defined for schema '\(override)' that is not defined in the OpenAPI document")
+            )
+        }
+    }
 }

Sources/_OpenAPIGeneratorCore/TypeOverrides.swift

@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+/// Type containing overrides for schema types.
+public struct TypeOverrides: Sendable {
+    /// A dictionary of overrides for replacing the types generated from schemas with manually provided types
+    public var schemas: [String: String]
+
+    /// Creates a new instance of `TypeOverrides`
+    /// - Parameter schemas: A dictionary mapping schema names to their override types.
+    public init(schemas: [String: String] = [:]) { self.schemas = schemas }
+
+    /// A Boolean value indicating whether there are no overrides.
+    public var isEmpty: Bool { schemas.isEmpty }
+}

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

@@ -34,6 +34,7 @@ extension _GenerateOptions {
         let resolvedAdditionalImports = resolvedAdditionalImports(config)
         let resolvedNamingStragy = resolvedNamingStrategy(config)
         let resolvedNameOverrides = resolvedNameOverrides(config)
+        let resolvedTypeOverrides = resolvedTypeOverrides(config)
         let resolvedFeatureFlags = resolvedFeatureFlags(config)
         let configs: [Config] = sortedModes.map {
             .init(
@@ -43,11 +44,19 @@ extension _GenerateOptions {
                 filter: config?.filter,
                 namingStrategy: resolvedNamingStragy,
                 nameOverrides: resolvedNameOverrides,
+                typeOverrides: resolvedTypeOverrides,
                 featureFlags: resolvedFeatureFlags
             )
         }
         let (diagnostics, finalizeDiagnostics) = preparedDiagnosticsCollector(outputPath: diagnosticsOutputPath)
         let doc = self.docPath
+        let typeOverridesDescription = """
+
+                - Schemas: \(resolvedTypeOverrides.schemas.isEmpty ? "<none>" : resolvedTypeOverrides.schemas
+            .sorted(by: { $0.key < $1.key })
+            .map { "\"\($0.key)\"->\"\($0.value)\"" }
+            .joined(separator: ", "))
+            """
         print(
             """
             Swift OpenAPI Generator is running with the following configuration:
@@ -59,6 +68,7 @@ extension _GenerateOptions {
             - Name overrides: \(resolvedNameOverrides.isEmpty ? "<none>" : resolvedNameOverrides
                 .sorted(by: { $0.key < $1.key })
                 .map { "\"\($0.key)\"->\"\($0.value)\"" }.joined(separator: ", "))
+            - Type overrides: \(resolvedTypeOverrides.isEmpty ? "<none>" : typeOverridesDescription)
             - 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

@@ -93,6 +93,13 @@ extension _GenerateOptions {
     /// - Parameter config: The configuration specified by the user.
     /// - 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 {
+        if let typeOverrides = config?.typeOverrides { return TypeOverrides(schemas: typeOverrides.schemas ?? [:]) }
+        return TypeOverrides()
+    }
 
     /// Returns a list of the feature flags requested by the user.
     /// - Parameter config: The configuration specified by the user.

Sources/swift-openapi-generator/UserConfig.swift

@@ -41,6 +41,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?
 
@@ -54,6 +57,13 @@ struct _UserConfig: Codable {
         case filter
         case namingStrategy
         case nameOverrides
+        case typeOverrides
         case featureFlags
     }
+
+    struct TypeOverrides: Codable {
+
+        /// A dictionary of overrides for replacing the types generated from schemas with manually provided types
+        var schemas: [String: String]?
+    }
 }