apple · czechboy0 · Dec 11, 2023 · Dec 11, 2023 · Dec 11, 2023
diff --git a/README.md b/README.md
@@ -1,6 +1,7 @@
 # Swift OpenAPI Generator Runtime
 
 [![](https://img.shields.io/badge/docc-read_documentation-blue)](https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation)
+[![](https://img.shields.io/github/v/release/apple/swift-openapi-runtime)](https://github.com/apple/swift-openapi-runtime/releases)
 [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fapple%2Fswift-openapi-runtime%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/apple/swift-openapi-runtime)
 [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fapple%2Fswift-openapi-runtime%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/apple/swift-openapi-runtime)
 
@@ -10,27 +11,26 @@ This library provides common abstractions and helper functions used by the clien
 
 It contains:
 - Common types used in the code generated by the `swift-openapi-generator` package plugin.
-- Protocol definitions for pluggable layers, including `ClientTransport`, `ServerTransport`, and middleware.
+- Protocol definitions for pluggable layers, including [`ClientTransport`](https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation/openapiruntime/clienttransport), [`ServerTransport`](https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation/openapiruntime/servertransport), [`ClientMiddleware`](https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation/openapiruntime/clientmiddleware), and [`ServerMiddleware`](https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation/openapiruntime/servermiddleware).
+
+Many of the HTTP currency types used are defined in the [Swift HTTP Types](https://github.com/apple/swift-http-types) library.
+
+> Tip: Check out the [example projects](https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/checking-out-an-example-project) focused on middlewares.
 
 ## Usage
 
 Add the package dependency in your `Package.swift`:
 
 ```swift
-.package(
-    url: "https://github.com/apple/swift-openapi-runtime",
-    exact: "1.0.0-alpha.1"
-),
+.package(url: "https://github.com/apple/swift-openapi-runtime", from: "1.0.0"),
 ```
 
-Note that this repository does not have a 1.0 tag yet, so the API is not stable.
-
 Next, in your target, add `OpenAPIRuntime` to your dependencies:
 
 ```swift
 .target(name: "MyTarget", dependencies: [
     .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
-],
+]),
 ```
 
 The next step depends on your use case.
@@ -45,17 +45,13 @@ Swift OpenAPI Generator generates client and server code that is designed to be
 
 Implement a new transport or middleware by providing a type that adopts one of the protocols from the runtime library:
 
-* `ClientTransport`
-* `ClientMiddleware`
-* `ServerTransport`
-* `ServerMiddleware`
+* [`ClientTransport`](https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation/openapiruntime/clienttransport)
+* [`ClientMiddleware`](https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation/openapiruntime/clientmiddleware)
+* [`ServerTransport`](https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation/openapiruntime/servertransport)
+* [`ServerMiddleware`](https://swiftpackageindex.com/apple/swift-openapi-runtime/documentation/openapiruntime/servermiddleware)
 
 You can also publish your transport or middleware as a Swift package to allow others to use it with their generated code.
 
-## Reporting issues
-
-Please report any issues related to this library in the [swift-openapi-generator](https://github.com/apple/swift-openapi-generator/issues) repository.
-
 ## Documentation
 
 To learn more, check out the full [documentation][2].

diff --git a/Sources/OpenAPIRuntime/Base/Base64EncodedData.swift b/Sources/OpenAPIRuntime/Base/Base64EncodedData.swift
@@ -14,7 +14,7 @@
 
 import Foundation
 
-/// Provides a route to encode or decode base64-encoded data
+/// A type for converting data as a base64 string.
 ///
 /// This type holds raw, unencoded, data as a slice of bytes. It can be used to encode that
 /// data to a provided `Encoder` as base64-encoded data or to decode from base64 encoding when

diff --git a/Sources/OpenAPIRuntime/Documentation.docc/Documentation.md b/Sources/OpenAPIRuntime/Documentation.docc/Documentation.md
@@ -8,29 +8,26 @@ This library provides common abstractions and helper functions used by the clien
 
 It contains:
 - Common types used in the code generated by the `swift-openapi-generator` package plugin.
-- Protocol definitions for pluggable layers, including ``ClientTransport``, ``ServerTransport``, and middleware.
+- Protocol definitions for pluggable layers, including ``ClientTransport``, ``ServerTransport``, ``ClientMiddleware``, and ``ServerMiddleware``.
 
 Many of the HTTP currency types used are defined in the [Swift HTTP Types](https://github.com/apple/swift-http-types) library.
 
+> Tip: Check out the [example projects](https://swiftpackageindex.com/apple/swift-openapi-generator/documentation/swift-openapi-generator/checking-out-an-example-project) focused on middlewares.
+
 ### Usage
 
 Add the package dependency in your `Package.swift`:
 
 ```swift
-.package(
-    url: "https://github.com/apple/swift-openapi-runtime",
-    exact: "1.0.0-alpha.1"
-),
+.package(url: "https://github.com/apple/swift-openapi-runtime", from: "1.0.0"),
 ```
 
-Note that this repository does not have a 1.0 tag yet, so the API is not stable.
-
 Next, in your target, add `OpenAPIRuntime` to your dependencies:
 
 ```swift
 .target(name: "MyTarget", dependencies: [
     .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
-],
+]),
 ```
 
 The next step depends on your use case.
@@ -52,19 +49,15 @@ Implement a new transport or middleware by providing a type that adopts one of t
 
 You can also publish your transport or middleware as a Swift package to allow others to use it with their generated code.
 
-### Reporting issues
-
-Please report any issues related to this library in the [swift-openapi-generator](https://github.com/apple/swift-openapi-generator/issues) repository.
-
 ## Topics
 
 ### Essentials
 - ``ClientTransport``
 - ``ServerTransport``
-
-### Customization
 - ``ClientMiddleware``
 - ``ServerMiddleware``
+
+### Customization
 - ``Configuration``
 - ``DateTranscoder``
 - ``ISO8601DateTranscoder``

diff --git a/Sources/OpenAPIRuntime/Interface/ClientTransport.swift b/Sources/OpenAPIRuntime/Interface/ClientTransport.swift
@@ -41,34 +41,19 @@ import struct Foundation.URL
 ///
 ///     let transport = URLSessionTransport()
 ///
-/// Create the base URL of the server to call using your client. If the server
-/// URL was defined in the OpenAPI document, you find a generated method for it
-/// on the `Servers` type, for example:
-///
-///     let serverURL = try Servers.server1()
-///
 /// Instantiate the `Client` type generated by the Swift OpenAPI Generator for
 /// your provided OpenAPI document. For example:
 ///
 ///     let client = Client(
-///         serverURL: serverURL,
+///         serverURL: URL(string: "https://example.com")!,
 ///         transport: transport
 ///     )
 ///
 /// Use the client to make HTTP calls defined in your OpenAPI document. For
 /// example, if the OpenAPI document contains an HTTP operation with
 /// the identifier `checkHealth`, call it from Swift with:
 ///
-///     let response = try await client.checkHealth(.init())
-///     switch response {
-///         case .ok(let okPayload):
-///             // ...
-///
-///         // Handle any HTTP status code not documented in
-///         // your OpenAPI document.
-///         case .undocumented(let statusCode, _):
-///             // ...
-///     }
+///     let response = try await client.checkHealth()
 ///
 /// The generated operation method takes an `Input` type unique to
 /// the operation, and returns an `Output` type unique to the operation.
@@ -107,16 +92,13 @@ import struct Foundation.URL
 /// Then in your test code, instantiate and provide the test transport to your
 /// generated client instead:
 ///
-///     let transport = TestTransport()
+///     var transport = TestTransport()
 ///     transport.isHealthy = true // for HTTP status code 200 (success)
-///     transport.isHealthy = false // for HTTP status code 500 (failure)
-///     let serverURL = try Servers.server1()
 ///     let client = Client(
-///         serverURL: serverURL,
+///         serverURL: URL(string: "https://example.com")!,
 ///         transport: transport
 ///     )
-///     let response = try await client.checkHealth(.init())
-///     // ...
+///     let response = try await client.checkHealth()
 ///
 /// Implementing a test client transport is just one way to help test your
 /// code that integrates with a generated client. Another is to implement
@@ -172,7 +154,7 @@ public protocol ClientTransport: Sendable {
 /// the middleware to the initializer of the generated `Client` type:
 ///
 ///     let client = Client(
-///         serverURL: serverURL,
+///         serverURL: URL(string: "https://example.com")!,
 ///         transport: transport,
 ///         middlewares: [
 ///             loggingMiddleware,
@@ -181,8 +163,7 @@ public protocol ClientTransport: Sendable {
 ///
 /// Then make a call to one of the generated client methods:
 ///
-///     let response = try await client.checkHealth(.init())
-///     // ...
+///     let response = try await client.checkHealth()
 ///
 /// As part of the invocation of `checkHealth`, the client first invokes
 /// the middlewares in the order you provided them, and then passes the request

diff --git a/Sources/OpenAPIRuntime/Interface/ServerTransport.swift b/Sources/OpenAPIRuntime/Interface/ServerTransport.swift
@@ -71,20 +71,19 @@ import HTTPTypes
 ///
 /// Create the URL where the server will run. The path of the URL is extracted
 /// by the transport to create a common prefix (such as `/api/v1`) that might
-/// be expected by the clients. If the server URL is defined in the OpenAPI
-/// document, find the generated method for it on the `Servers` type,
-/// for example:
-///
-///     let serverURL = try Servers.server1()
+/// be expected by the clients.
 ///
 /// Register the generated request handlers by calling the method generated
 /// on the `APIProtocol` protocol:
 ///
-///     try handler.registerHandlers(on: transport, serverURL: serverURL)
+///     try handler.registerHandlers(
+///         on: transport,
+///         serverURL: URL(string: "/api/v1")!
+///     )
 ///
 /// Start the server by following the documentation of your chosen transport:
 ///
-///     try app.run()
+///     try await app.execute()
 ///
 /// ### Implement a custom server transport
 ///
@@ -161,7 +160,7 @@ public protocol ServerTransport {
 ///
 ///     try handler.registerHandlers(
 ///         on: transport,
-///         serverURL: serverURL,
+///         serverURL: URL(string: "/api/v1")!,
 ///         middlewares: [
 ///             loggingMiddleware,
 ///         ]