Allow substituting types

Examples/replace-types-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/replace-types-example/Package.swift

@@ -0,0 +1,37 @@
+// swift-tools-version:5.9
+//===----------------------------------------------------------------------===//
+//
+// 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: "replace-types-example",
+    platforms: [.macOS(.v14)],
+    products: [
+        .library(name: "Types", targets: ["Types"]),
+    ],
+    dependencies: [
+        .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")]
+        ),
+        .target(
+            name: "ExternalLibrary"
+        ),
+    ]
+)

Examples/replace-types-example/README.md

@@ -0,0 +1,40 @@
+# Replacing 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 you can structure a Swift package to share the types
+from an OpenAPI document between a client and server module by having a common
+target that runs the generator in `types` mode only.
+
+This allows you to write extensions or other helper functions that use these
+types and use them in both the client and server code.
+
+## Usage
+
+Build and run the server using:
+
+```console
+% swift run hello-world-server
+Build complete!
+...
+info HummingBird : [HummingbirdCore] Server started and listening on 127.0.0.1:8080
+```
+
+Then, in another terminal window, run the client:
+
+```console
+% swift run hello-world-client
+Build complete!
++––––––––––––––––––+
+|+––––––––––––––––+|
+||Hello, Stranger!||
+|+––––––––––––––––+|
++––––––––––––––––––+
+```
+
+Note how the message is boxed twice: once by the server and once by the client,
+both using an extension on a shared type, defined in the `Types` module.

Examples/replace-types-example/Sources/ExternalLibrary/ExternalObject.swift

@@ -0,0 +1,4 @@
+public struct ExternalObject: Codable, Hashable, Sendable {
+    public let foo: String
+    public let bar: String
+}

Examples/replace-types-example/Sources/ExternalLibrary/PrimeNumber.swift

@@ -0,0 +1,35 @@
+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/replace-types-example/Sources/Types/Generated/Types.swift

@@ -0,0 +1,228 @@
+// Generated by swift-openapi-generator, do not modify.
+@_spi(Generated) import OpenAPIRuntime
+#if os(Linux)
+@preconcurrency import struct Foundation.URL
+@preconcurrency import struct Foundation.Data
+@preconcurrency import struct Foundation.Date
+#else
+import struct Foundation.URL
+import struct Foundation.Data
+import struct Foundation.Date
+#endif
+import Foundation
+import ExternalLibrary
+/// A type that performs HTTP operations defined by the OpenAPI document.
+package protocol APIProtocol: Sendable {
+    /// - Remark: HTTP `GET /user`.
+    /// - Remark: Generated from `#/paths//user/get(getUser)`.
+    func getUser(_ input: Operations.GetUser.Input) async throws -> Operations.GetUser.Output
+}
+
+/// Convenience overloads for operation inputs.
+extension APIProtocol {
+    /// - Remark: HTTP `GET /user`.
+    /// - Remark: Generated from `#/paths//user/get(getUser)`.
+    package func getUser(
+        query: Operations.GetUser.Input.Query = .init(),
+        headers: Operations.GetUser.Input.Headers = .init()
+    ) async throws -> Operations.GetUser.Output {
+        try await getUser(Operations.GetUser.Input(
+            query: query,
+            headers: headers
+        ))
+    }
+}
+
+/// Server URLs defined in the OpenAPI document.
+package enum Servers {
+    /// Example service deployment.
+    package enum Server1 {
+        /// Example service deployment.
+        package static func url() throws -> Foundation.URL {
+            try Foundation.URL(
+                validatingOpenAPIServerURL: "https://example.com/api",
+                variables: []
+            )
+        }
+    }
+    /// Example service deployment.
+    @available(*, deprecated, renamed: "Servers.Server1.url")
+    package static func server1() throws -> Foundation.URL {
+        try Foundation.URL(
+            validatingOpenAPIServerURL: "https://example.com/api",
+            variables: []
+        )
+    }
+}
+
+/// Types generated from the components section of the OpenAPI document.
+package enum Components {
+    /// Types generated from the `#/components/schemas` section of the OpenAPI document.
+    package enum Schemas {
+        /// - Remark: Generated from `#/components/schemas/UUID`.
+        package typealias Uuid = Foundation.UUID
+        /// - Remark: Generated from `#/components/schemas/User`.
+        package struct User: Codable, Hashable, Sendable {
+            /// - Remark: Generated from `#/components/schemas/User/id`.
+            package var id: Components.Schemas.Uuid?
+            /// - Remark: Generated from `#/components/schemas/User/name`.
+            package var name: Swift.String?
+            /// Creates a new `User`.
+            ///
+            /// - Parameters:
+            ///   - id:
+            ///   - name:
+            package init(
+                id: Components.Schemas.Uuid? = nil,
+                name: Swift.String? = nil
+            ) {
+                self.id = id
+                self.name = name
+            }
+            package enum CodingKeys: String, CodingKey {
+                case id
+                case name
+            }
+        }
+    }
+    /// Types generated from the `#/components/parameters` section of the OpenAPI document.
+    package enum Parameters {}
+    /// Types generated from the `#/components/requestBodies` section of the OpenAPI document.
+    package enum RequestBodies {}
+    /// Types generated from the `#/components/responses` section of the OpenAPI document.
+    package enum Responses {}
+    /// Types generated from the `#/components/headers` section of the OpenAPI document.
+    package enum Headers {}
+}
+
+/// API operations, with input and output types, generated from `#/paths` in the OpenAPI document.
+package enum Operations {
+    /// - Remark: HTTP `GET /user`.
+    /// - Remark: Generated from `#/paths//user/get(getUser)`.
+    package enum GetUser {
+        package static let id: Swift.String = "getUser"
+        package struct Input: Sendable, Hashable {
+            /// - Remark: Generated from `#/paths/user/GET/query`.
+            package struct Query: Sendable, Hashable {
+                /// The name of the user
+                ///
+                /// - Remark: Generated from `#/paths/user/GET/query/name`.
+                package var name: Swift.String?
+                /// Creates a new `Query`.
+                ///
+                /// - Parameters:
+                ///   - name: The name of the user
+                package init(name: Swift.String? = nil) {
+                    self.name = name
+                }
+            }
+            package var query: Operations.GetUser.Input.Query
+            /// - Remark: Generated from `#/paths/user/GET/header`.
+            package struct Headers: Sendable, Hashable {
+                package var accept: [OpenAPIRuntime.AcceptHeaderContentType<Operations.GetUser.AcceptableContentType>]
+                /// Creates a new `Headers`.
+                ///
+                /// - Parameters:
+                ///   - accept:
+                package init(accept: [OpenAPIRuntime.AcceptHeaderContentType<Operations.GetUser.AcceptableContentType>] = .defaultValues()) {
+                    self.accept = accept
+                }
+            }
+            package var headers: Operations.GetUser.Input.Headers
+            /// Creates a new `Input`.
+            ///
+            /// - Parameters:
+            ///   - query:
+            ///   - headers:
+            package init(
+                query: Operations.GetUser.Input.Query = .init(),
+                headers: Operations.GetUser.Input.Headers = .init()
+            ) {
+                self.query = query
+                self.headers = headers
+            }
+        }
+        @frozen package enum Output: Sendable, Hashable {
+            package struct Ok: Sendable, Hashable {
+                /// - Remark: Generated from `#/paths/user/GET/responses/200/content`.
+                @frozen package enum Body: Sendable, Hashable {
+                    /// - Remark: Generated from `#/paths/user/GET/responses/200/content/application\/json`.
+                    case json(Components.Schemas.User)
+                    /// The associated value of the enum case if `self` is `.json`.
+                    ///
+                    /// - Throws: An error if `self` is not `.json`.
+                    /// - SeeAlso: `.json`.
+                    package var json: Components.Schemas.User {
+                        get throws {
+                            switch self {
+                            case let .json(body):
+                                return body
+                            }
+                        }
+                    }
+                }
+                /// Received HTTP response body
+                package var body: Operations.GetUser.Output.Ok.Body
+                /// Creates a new `Ok`.
+                ///
+                /// - Parameters:
+                ///   - body: Received HTTP response body
+                package init(body: Operations.GetUser.Output.Ok.Body) {
+                    self.body = body
+                }
+            }
+            /// A success response with the user.
+            ///
+            /// - Remark: Generated from `#/paths//user/get(getUser)/responses/200`.
+            ///
+            /// HTTP response code: `200 ok`.
+            case ok(Operations.GetUser.Output.Ok)
+            /// The associated value of the enum case if `self` is `.ok`.
+            ///
+            /// - Throws: An error if `self` is not `.ok`.
+            /// - SeeAlso: `.ok`.
+            package var ok: Operations.GetUser.Output.Ok {
+                get throws {
+                    switch self {
+                    case let .ok(response):
+                        return response
+                    default:
+                        try throwUnexpectedResponseStatus(
+                            expectedStatus: "ok",
+                            response: self
+                        )
+                    }
+                }
+            }
+            /// Undocumented response.
+            ///
+            /// A response with a code that is not documented in the OpenAPI document.
+            case undocumented(statusCode: Swift.Int, OpenAPIRuntime.UndocumentedPayload)
+        }
+        @frozen package enum AcceptableContentType: AcceptableProtocol {
+            case json
+            case other(Swift.String)
+            package init?(rawValue: Swift.String) {
+                switch rawValue.lowercased() {
+                case "application/json":
+                    self = .json
+                default:
+                    self = .other(rawValue)
+                }
+            }
+            package var rawValue: Swift.String {
+                switch self {
+                case let .other(string):
+                    return string
+                case .json:
+                    return "application/json"
+                }
+            }
+            package static var allCases: [Self] {
+                [
+                    .json
+                ]
+            }
+        }
+    }
+}

Examples/replace-types-example/Sources/Types/openapi-generator-config.yaml

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

Examples/replace-types-example/Sources/Types/openapi.yaml

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