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
+    }
+}