Add example package using shared types in client and server (#592)

### Motivation

We get asked from time to time how to structure a package to share types
from an OpenAPI document between multiple targets, e.g. a client and a
server. This allows adopters to write extensions or other functionality
that uses the common types once, and use them from both downstream
modules.

### Modifications

Add an example package that combines the existing Hello World client and
server but factors the types generation into a separate module.

### Result

Another example package.

### Test Plan

- Tested locally, which produces the same result as in the example
README.
- CI.

Author: simonjbeaumont

Examples/shared-types-client-server-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/shared-types-client-server-example/Package.swift

@@ -0,0 +1,53 @@
+// 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: "shared-types-client-server-example",
+    platforms: [.macOS(.v13)],
+    products: [
+        .executable(name: "hello-world-client", targets: ["Client"]),
+        .executable(name: "hello-world-server", targets: ["Server"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-openapi-generator", from: "1.0.0"),
+        .package(url: "https://github.com/apple/swift-openapi-runtime", from: "1.0.0"),
+        .package(url: "https://github.com/apple/swift-openapi-urlsession", from: "1.0.0"),
+        .package(url: "https://github.com/swift-server/swift-openapi-hummingbird", from: "1.0.0"),
+    ],
+    targets: [
+        .target(
+            name: "Types",
+            dependencies: [.product(name: "OpenAPIRuntime", package: "swift-openapi-runtime")],
+            plugins: [.plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator")]
+        ),
+        .executableTarget(
+            name: "Client",
+            dependencies: [
+                "Types", .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
+                .product(name: "OpenAPIURLSession", package: "swift-openapi-urlsession"),
+            ],
+            plugins: [.plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator")]
+        ),
+        .executableTarget(
+            name: "Server",
+            dependencies: [
+                "Types", .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
+                .product(name: "OpenAPIHummingbird", package: "swift-openapi-hummingbird"),
+            ],
+            plugins: [.plugin(name: "OpenAPIGenerator", package: "swift-openapi-generator")]
+        ),
+    ]
+)

Examples/shared-types-client-server-example/README.md

@@ -0,0 +1,40 @@
+# Common types between client and server modules
+
+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/shared-types-client-server-example/Sources/Client/HelloWorldURLSessionClient.swift

@@ -0,0 +1,24 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 OpenAPIRuntime
+import OpenAPIURLSession
+import Foundation
+
+@main struct HelloWorldURLSessionClient {
+    static func main() async throws {
+        let client = Client(serverURL: URL(string: "http://localhost:8080/api")!, transport: URLSessionTransport())
+        let response = try await client.getGreeting()
+        print(try response.ok.body.json.boxed().message)
+    }
+}

Examples/shared-types-client-server-example/Sources/Client/openapi-generator-config.yaml

@@ -0,0 +1,5 @@
+generate:
+  - client
+accessModifier: internal
+additionalImports:
+  - Types

Examples/shared-types-client-server-example/Sources/Client/openapi.yaml

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

Examples/shared-types-client-server-example/Sources/Server/HelloWorldHummingbirdServer.swift

@@ -0,0 +1,36 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 OpenAPIRuntime
+import OpenAPIHummingbird
+import Hummingbird
+import Foundation
+import Types
+
+struct Handler: APIProtocol {
+    func getGreeting(_ input: Operations.getGreeting.Input) async throws -> Operations.getGreeting.Output {
+        let name = input.query.name ?? "Stranger"
+        let message = Components.Schemas.Greeting(message: "Hello, \(name)!")
+        return .ok(.init(body: .json(message.boxed())))
+    }
+}
+
+@main struct HelloWorldHummingbirdServer {
+    static func main() async throws {
+        let app = Hummingbird.HBApplication()
+        let transport = HBOpenAPITransport(app)
+        let handler = Handler()
+        try handler.registerHandlers(on: transport, serverURL: URL(string: "/api")!)
+        try await app.asyncRun()
+    }
+}

Examples/shared-types-client-server-example/Sources/Server/openapi-generator-config.yaml

@@ -0,0 +1,5 @@
+generate:
+  - server
+accessModifier: internal
+additionalImports:
+  - Types

Examples/shared-types-client-server-example/Sources/Server/openapi.yaml

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

Examples/shared-types-client-server-example/Sources/Types/Extensions.swift

@@ -0,0 +1,41 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+extension Components.Schemas.Greeting {
+    package func boxed(maxBoxWidth: Int = 80) -> Self {
+        // Reflow the text.
+        let maxTextLength = maxBoxWidth - 4
+        var reflowedLines: [Substring] = []
+        for var line in message.split(whereSeparator: \.isNewline) {
+            while !line.isEmpty {
+                let prefix = line.prefix(maxTextLength)
+                reflowedLines.append(prefix)
+                line = line.dropFirst(prefix.count)
+            }
+        }
+
+        // Determine the box size (might be smaller than max).
+        let longestLineCount = reflowedLines.map(\.count).max()!
+        let horizontalEdge = "+\(String(repeating: "–", count: longestLineCount))+"
+
+        var boxedMessageLines: [String] = []
+        boxedMessageLines.reserveCapacity(reflowedLines.count + 2)
+        boxedMessageLines.append(horizontalEdge)
+        for line in reflowedLines {
+            boxedMessageLines.append("|\(line.padding(toLength: longestLineCount, withPad: " ", startingAt: 0))|")
+        }
+        boxedMessageLines.append(horizontalEdge)
+        return Self(message: boxedMessageLines.joined(separator: "\n"))
+    }
+}