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(