Use operation summary and description in generated function docs (#67)

Motivation

For generated functions for each operations we generate reference documentation. Currently this only states the HTTP information and the operation ID, and doesn’t include either the summary or the description that may be present in the OpenAPI document.

Modifications

Change the reference documentation to include both the summary and the description if they are provided.

Result

Reference documentation for operation functions contains the documentation from the OpenAPI document.

Test Plan

The OpenAPI document used in the reference test includes operations with and without these fields.

Resolves

Resolves #64.

Signed-off-by: Si Beaumont beaumont@apple.com

Swift OpenAPI Generator

Generate Swift client and server code from an OpenAPI document.

Overview

OpenAPI is an open specification for documenting HTTP APIs.

Swift OpenAPI Generator is a Swift package plugin that can generate the ceremony code required to make API calls, or implement API servers.

Repository organization

The Swift OpenAPI Generator project is split across multiple repositories to enable extensibility and minimize dependencies in your project.

swift-openapi-generator (source, docs) provides the plugin.

swift-openapi-runtime (source, docs) provides a library with common types and abstractions used by the generated code.

See the generator in action in Meet Swift OpenAPI Generator from WWDC23.

Choose one of the transports listed below, or create your own by adopting the ClientTransport or ServerTransport protocol:

Repository	Type	Description
apple/swift-openapi-urlsession	Client	Uses `URLSession` from Foundation.
swift-server/swift-openapi-async-http-client	Client	Uses `HTTPClient` from AsyncHTTPClient.
swift-server/swift-openapi-vapor	Server	Uses Vapor.
swift-server/swift-openapi-hummingbird	Server	Uses Hummingbird.

Requirements and supported features

Swift 5.8
OpenAPI 3.0.x

Supported platforms and minimum versions

The generator is used during development and is supported on macOS and Linux.

The generated code, runtime library, and transports are supported on more platforms, listed below.

Component	macOS	Linux	iOS	tvOS	watchOS
Generator plugin and CLI	✅ 10.15+	✅	❌	❌	❌
Generated code, runtime, transports	✅ 10.15+	✅	✅ 13+	✅ 13+	✅ 6+

Documentation

To get started, check out the full documentation, which contains step-by-step tutorials!