apigenie-generator
apigenie-generator generates code and data from an OpenAPI or AsyncAPI document, servers from a
GraphQL schema, gRPC code from a Protobuf file set, documentation sites from OpenAPI, Swagger,
AsyncAPI, GraphQL and Protobuf files, and validation schemas from JSON Schemas. It is a separate
executable, installed next to
apigenie by every package, the npm package and the Docker image (run it there with
docker run --entrypoint apigenie-generator mykulyak/apigenie ...). Before 0.9.0 the generators
were the apigenie generate command: apigenie generate client fetch ... is now
apigenie-generator client fetch ..., with the same options and configuration.
Usage
apigenie-generator GENERATOR [TARGET] [...OPTIONS] INPUT_FILE
apigenie-generator --version | --credits | --license [LIBRARY] | --license-list
client go, client csharp, client java, client python, server go, server spring and
server aspnet read both kinds of documents: the generator is picked by the document, OpenAPI
(3.0, 3.1, 3.2) or AsyncAPI (3.x). Since 0.12.0, the client and server generators of OpenAPI
documents also read Swagger 2.0 documents (see Swagger 2.0 input).
server absinthe reads a GraphQL schema (.graphql, .graphqls or .gql).
Every code generator takes -c, --config (a configuration file, see
Configuration), -o, --output (the output directory) and
--package-name / --package-version; several take generator options as -p name=value. The
pages below list the options of each target.
Swagger 2.0 input
Since 0.12.0, the client and server generators of OpenAPI documents read Swagger 2.0 documents
too. They convert the document in memory to OpenAPI 3.2, as
apigenie convert --to openapi32 does, and generate from the
result. The convert command is experimental: the
converted document can change between releases, while the code generated from it follows the
compatibility of each target. The in-memory conversion
differs from the command in three ways:
- Polymorphism becomes a union. A definition with a
discriminatorbecomes theoneOfof its shapes, so the generators write a type or a class per shape; one that extends another definition with a discriminator stays an object, with a warning. The union keeps only itstitle,description,discriminatorandx-extensions other thanx-nullable. When some of the definitions extending it withallOfhave anx-discriminator-value, only those are shapes, and their values are the discriminator’smapping. Without values, every definition extending it is a shape, told apart by its name. A shape gets the base’s other keywords (type,properties,required, …) in place of the reference. A definition that isn’t a shape keeps the reference, so it combines the union with its own keywords. - What it approximates or repairs is reported. Each is a warning at its position in the Swagger document.
- A reference to another document is an error. The command copies it unchanged; the generators
stop with exit status 2 and generate nothing. Bundle the document first with
apigenie bundle.
For example, with two definitions extending Pet:
definitions:
Pet:
type: object
discriminator: kind
required: [kind, name]
properties: { kind: { type: string }, name: { type: string } }
Cat:
x-discriminator-value: cat
allOf:
- $ref: '#/definitions/Pet'
- { type: object, properties: { indoor: { type: boolean } } }
Dog:
x-discriminator-value: dog
allOf:
- $ref: '#/definitions/Pet'
- { type: object, properties: { breed: { type: string } } }
client fetch generates Pet as the union of Cat and Dog, told apart by kind:
export type Pet = Cat | Dog;
export type Cat = { kind: string; name: string } & { indoor?: boolean };
export type Dog = { kind: string; name: string } & { breed?: string };
A warning names the file, line and column, e.g.
swagger.yaml:7:7 warning the schemes of an operation have no counterpart and are dropped. The
generators’ own warnings point to the Swagger document too. A document with a swagger version
other than 2.0 is rejected (Unsupported Swagger version '1.2' in 'swagger.yaml', expected 2.0),
and one that isn’t a valid Swagger 2.0 document is rejected with its problems listed
(Errors reading Swagger file); both exit with status 2. Overlays given with --overlay apply to
the Swagger document before it is converted, so their targets follow its structure, e.g.
$.definitions.Pet.
Swagger 2.0 can’t express some of what the conformance fixture checks, such as callbacks, cookie parameters or a body schema per media type; the conformance results mark those features as out of scope for 2.0.
Conformance checks
The codegen conformance suite checks the generators at three levels:
- Snapshots and features. Each generator’s test suite generates from the shared fixtures, compares the output byte for byte with its snapshots, and checks each feature of the fixture against the target’s manifest, which also lists the features the target doesn’t support yet.
- Type checking and linting. The generated code goes through the target language’s type checker and linter, with pinned versions.
- Contract tests. A generated client calls every operation of the fixture through the validating proxy, and a generated server receives generated requests and a hand-written request set; the traffic is validated against the fixture. Event-driven targets run against brokers.
The fixtures model the fictional Carpet Express shipping service. Its OpenAPI 3.1 definition and AsyncAPI 3.0 definition are available as downloads. The suite generates from the OpenAPI 3.2 document. Level 1 runs on its 3.1, 3.0 and, since 0.12.0, Swagger 2.0 variants too; at Levels 2 and 3 they serve to look into a target whose 3.2 output fails early.
Levels 2 and 3 run in the release gate on Linux, which a release can’t skip: every generated client and server with Level 3 runs in contract tests before a release. The conformance results show each target’s results, for the latest release and the development version, and the features the targets don’t support yet with the reasons their manifests give; each target’s page has the same in its Verification section. Coverage varies by target, and a snapshot match is not a guarantee of complete standard support.
Each target has a support tier, shown at the top of its page. Tier 1 targets go through all three levels, and their unsupported features are worked on first; today they are nine OpenAPI clients and servers. Tier 2 targets go through the same three levels and can leave features unsupported. The MCP server is a Tier 2 target labelled experimental, because MCP and its SDK are still changing. The Zod generator, the Rust client and the axum server are experimental: they have no Level 3 contract tests yet.
Overlays
Every target reading OpenAPI or AsyncAPI documents takes --overlay FILE: an
OpenAPI Overlay (1.0 to 1.2) applied to the input before
generating. Repeat it to apply several, in order. The vendor extensions a target reads (each target’s
page lists them, and Specification extensions lists them all) can then live in an overlay of that target instead of in the API description:
apigenie-generator server spring openapi.yaml --overlay spring.overlay.yaml -o server
- The overlays listed under
commands.generate.<target>.overlayin the configuration file, relative to it, apply first, then the--overlayones. - An AsyncAPI document that references other files is bundled before the overlays apply.
- An action whose target selects nothing prints a warning with its position, e.g.
spring.overlay.yaml:12:5: action #3 ($.paths['/pickups'].get) selects no nodes.. With--strictit is an error: nothing is generated and the exit status is 2. - Warnings and errors about a value an overlay set point at the overlay
(
spring.overlay.yaml:9:9 Warning ...); the others keep their line in the input.
docs, which reads several inputs, and the targets of GraphQL schemas and .proto files don’t;
for docs, apply the overlays with apigenie overlay first.
Check that generated code is up to date
Every target of client, server and schema takes --check (since 0.12.0): the generator runs
as usual but keeps what it writes in memory, compares each file with the one in the output
directory, and writes nothing. The files that would be created or changed are printed on standard
output, one per line, relative to the current directory, after the generator’s messages. When
there are any, a summary follows on standard error and the exit status is 1; otherwise the exit
status is 0. With --json, the status report holds the
list in output and the summary in messages. After a value is added to an enum of the document:
apigenie-generator client fetch openapi.yaml -o client --check
client/src/types.ts
1 generated file(s) would change and 0 would be created.
- The generator sees the output directory as it is, so the files it writes only when they are
missing (each target’s page names them, for example the controllers of
server spring) are left out of the comparison once they exist. - Files in the output directory that the generator doesn’t write are not compared: a file left behind by an operation removed from the document is not reported. Delete the output directory before generating to drop such files.
- Generating twice from the same input, configuration and generator version gives the same
bytes: the files hold no date and no absolute path. A new generator version can change the
files:
client javaandserver springwrite the version in thecommentselement of@Generated. Since 0.12.0client javaandserver springleave the date out of@Generated.hideGenerationTimestamp: falsebrings it back, with the date ofgenerationTimestampwhen it is set.
Generate a client and a server runs the check in a pull request.
Exit status
apigenie-generator exits with 0 when the code was generated and with 2 when the options, the
configuration, an overlay or the input document can’t be used (with --strict, also when an
overlay action selects nothing), or no generator is named (apigenie-generator
or apigenie-generator client alone print the help). With --check it exits with 1 when a file
would be created or changed; see the
exit statuses shared by the five binaries.
apigenie generate ... exits with 2 and prints the apigenie-generator command to run instead.
schema zod, client rust and server axum are
experimental.
From OpenAPI
Clients
| Name | Summary |
|---|---|
| client csharp | C# client for HttpClient (.NET 8) |
| client elixir | Elixir client on Req |
| client fetch | TypeScript client for the Fetch API |
| client go | Go client for net/http |
| client java | Java client for Spring RestClient, RestTemplate, OpenFeign or HTTP interfaces |
| client python | Python client on httpx and Pydantic |
| client rust | Rust client crate on reqwest and serde (experimental) |
| client swift | Swift client on URLSession (experimental) |
Servers
| Name | Summary |
|---|---|
| server aspnet | ASP.NET Core server (Minimal APIs) |
| server axum | Rust server crate on axum (experimental) |
| server express | TypeScript Express server |
| server fastapi | Python FastAPI server |
| server go | Go net/http server |
| server hummingbird | Swift server on Hummingbird 2 (experimental) |
| server mcp | MCP server in TypeScript: a tool per operation (experimental) |
| server orpc | TypeScript server on oRPC |
| server phoenix | Elixir Phoenix 1.7 server |
| server spring | Spring Boot server |
| server vapor | Swift server on Vapor 4 (experimental) |
Documentation and data
| Name | Summary |
|---|---|
| docs | a documentation site; also from Swagger 2.0, AsyncAPI, GraphQL and Protobuf files, several at once |
| data | example data for a schema of the document |
From AsyncAPI
| Name | Summary |
|---|---|
| client csharp | C# Kafka client library |
| client elixir | Elixir client library (WebSocket channels on Mint.WebSocket, Kafka on brod) |
| client go | Go Kafka client package |
| client java | Java Kafka client library on the Apache Kafka client |
| client kafkajs | TypeScript Kafka client on KafkaJS |
| client python | Python asyncio Kafka client on aiokafka |
| client ws | TypeScript WebSocket client |
| server aspnet | ASP.NET Core Kafka application |
| server faststream | Python FastStream application (Kafka, RabbitMQ, MQTT) |
| server go | Go Kafka application |
| server kafkajs | TypeScript Kafka application on KafkaJS |
| server phoenix | Elixir Phoenix application (WebSocket channels, Kafka on Broadway and brod) |
| server spring | Spring Boot Kafka application |
| server ws | Node.js WebSocket server |
From GraphQL
| Name | Summary |
|---|---|
| server absinthe | Elixir Absinthe server of the schema (import_sdl) |
From Protobuf
| Name | Summary |
|---|---|
| client elixir | Elixir gRPC client on elixir-grpc |
| server elixir-grpc | Elixir gRPC server on elixir-grpc |
From JSON Schema
| Name | Summary |
|---|---|
| schema zod | Zod schemas |