Swift OpenAPI Generator

The project is modularized to allow for different HTTP clients and web frameworks. Depending on your needs, you may need to import specific transport packages:

• Clients:
  • apple/swift-openapi-urlsession: ClientTransport using URLSession.
  • swift-server/swift-openapi-async-http-client: ClientTransport using AsyncHTTPClient.
• Servers:
  • vapor/swift-openapi-vapor: ServerTransport using Vapor.
  • hummingbird-project/swift-openapi-hummingbird: ServerTransport using Hummingbird.
  • awslabs/swift-openapi-lambda: ServerTransport using AWS Lambda.

The project is modularized into several repositories to allow for different HTTP clients and web frameworks. The core logic resides in the generator and runtime, while specific transports are provided by separate packages:

To make a standalone schema optional, you must define it as nullable. The syntax depends on the OpenAPI/JSON Schema version used:

• OpenAPI 3.0.3 (JSON Schema Draft 5): Use the nullable: true field.
• OpenAPI 3.1.0 (JSON Schema 2020-12): Include null in the type array.

Nullability is propagated through references; the generator checks the target schema of a reference to determine optionality.

# OpenAPI 3.0.3
MyOptionalString:
  type: string
  nullable: true

# OpenAPI 3.1.0
MyOptionalString:
  type: [string, null]

The generator uses an algorithm to minimize the number of boxed types, as boxing can be less performant than non-recursive value types.

The Algorithm:

1. It iterates through types defined in #/components/schemas in the order they appear in the OpenAPI document.
2. It walks the references for each type.
3. When a reference cycle is detected, it selects the first type in the cycle (the one that closed the cycle) to be boxed.

Example: If the reference path is A -> B -> C -> B, the algorithm identifies that the cycle closes at B, so it chooses type B for boxing.

The following behaviors are not considered part of the Swift OpenAPI Generator API and may change without warning. You should be prepared for these to change when updating the generator:

• The number and names of files generated by the CLI and plugins.
• The SPI (Service Provider Interface) provided by the OpenAPIRuntime library (marked with @_spi(Generated)).
• The business logic within the generated code (any code that is not part of the generated code's own public API).
• The diagnostics emitted by the generator, including their severity levels and printed descriptions.

You can use the filter configuration key in your openapi-generator-config.yaml to instruct the generator to only process a subset of your OpenAPI document. This is highly effective for large APIs (like GitHub's) where you only need a specific set of endpoints or types.

Filtering reduces:

• The amount of unused code generated.
• Compilation times.
• The overall footprint of the generated code in your codebase.

When you specify a filter, the generator includes the requested items along with the transitive closure of all components they depend on. For example, if you include a path, all schemas referenced by that path's operations and responses will also be included.

# openapi-generator-config.yaml
generate:
- types
- client

filter:
  tags:
  - issues

To test your application without a live server, you can use the MockClient.

To make your code testable, design your APIs to accept any APIProtocol instead of the concrete Client type. Since the generated Client conforms to APIProtocol, you can inject a MockClient during testing to simulate various server responses and failure conditions.

Helper methods follow a deterministic naming pattern. If you are debugging generated code, you can predict the method name using this pattern:

{set,get}{required/optional/omit if both}{location}As{strategy}

Example Patterns:

• setRequiredRequestBodyAsJSON(value:)
• getOptionalQueryItemAsURI()
• setHeaderFieldAsURI(value:)

method name: {set,get}{required/optional/omit if both}{location}As{strategy}
method parameters: value or type of value