ReferenceGeneratorapigenie-generator

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). Swagger 2.0 documents can be converted first with convert --to openapi32. 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.

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; its 3.1 and 3.0 variants serve to look into a target whose 3.2 output fails early.

Coverage varies by target, and a snapshot match is not a guarantee of complete standard support. Each target’s reference documents its limitations, such as the Fetch client’s handling of servers and streaming responses. The experimental Zod generator has no Level 3 contract tests.

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) 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.

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); see the exit statuses shared by the four binaries. apigenie generate ... exits with 2 and prints the apigenie-generator command to run instead. schema zod is 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

Servers

Name Summary
server aspnet ASP.NET Core server (Minimal APIs)
server express TypeScript Express server
server fastapi Python FastAPI server
server go Go net/http server
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

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