From 81ab3e275dd59e53a559182c8de6128541824891 Mon Sep 17 00:00:00 2001 From: Honza Dvorsky Date: Mon, 11 Dec 2023 11:25:58 +0100 Subject: [PATCH] [Docs] Prep 1.0.0 --- README.md | 28 +++++++--------- .../Base/Base64EncodedData.swift | 2 +- .../Documentation.docc/Documentation.md | 21 ++++-------- .../Interface/ClientTransport.swift | 33 ++++--------------- .../Interface/ServerTransport.swift | 15 ++++----- 5 files changed, 34 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index b74f3b9a..75c8720f 100644 --- 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 index 7af50f72..ce3c43fa 100644 --- 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 index 2e6f3399..8b16cf53 100644 --- 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 index 200520ca..cb20c651 100644 --- a/Sources/OpenAPIRuntime/Interface/ClientTransport.swift +++ b/Sources/OpenAPIRuntime/Interface/ClientTransport.swift @@ -41,17 +41,11 @@ 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 /// ) /// @@ -59,16 +53,7 @@ import struct Foundation.URL /// 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 index 2ee147bc..40e16e8f 100644 --- 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, /// ]