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 discriminator becomes the oneOf of 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 its title, description, discriminator and x- extensions other than x-nullable. When some of the definitions extending it with allOf have an x-discriminator-value, only those are shapes, and their values are the discriminator’s mapping. 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:

  1. 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.
  2. Type checking and linting. The generated code goes through the target language’s type checker and linter, with pinned versions.
  3. 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>.overlay in the configuration file, relative to it, apply first, then the --overlay ones.
  • 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 --strict it 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 java and server spring write the version in the comments element of @Generated. Since 0.12.0 client java and server spring leave the date out of @Generated. hideGenerationTimestamp: false brings it back, with the date of generationTimestamp when 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
Was this helpful?