# apigenie-generator

Source: https://apigenie.pl/docs/reference/generator
See also: [Conformance results](https://apigenie.pl/docs/reference/generator/conformance.md), [docs](https://apigenie.pl/docs/reference/generator/docs.md), [data](https://apigenie.pl/docs/reference/generator/data.md), [schema zod](https://apigenie.pl/docs/reference/generator/schema-zod.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir.md), [client fetch](https://apigenie.pl/docs/reference/generator/client-fetch.md), [client go](https://apigenie.pl/docs/reference/generator/client-go.md), [client java](https://apigenie.pl/docs/reference/generator/client-java.md), [client python](https://apigenie.pl/docs/reference/generator/client-python.md), [client rust](https://apigenie.pl/docs/reference/generator/client-rust.md), [client swift](https://apigenie.pl/docs/reference/generator/client-swift.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet.md), [server axum](https://apigenie.pl/docs/reference/generator/server-axum.md), [server express](https://apigenie.pl/docs/reference/generator/server-express.md), [server fastapi](https://apigenie.pl/docs/reference/generator/server-fastapi.md), [server go](https://apigenie.pl/docs/reference/generator/server-go.md), [server hummingbird](https://apigenie.pl/docs/reference/generator/server-hummingbird.md), [server mcp](https://apigenie.pl/docs/reference/generator/server-mcp.md), [server orpc](https://apigenie.pl/docs/reference/generator/server-orpc.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring.md), [server vapor](https://apigenie.pl/docs/reference/generator/server-vapor.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp-asyncapi.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-asyncapi.md), [client go](https://apigenie.pl/docs/reference/generator/client-go-asyncapi.md), [client java](https://apigenie.pl/docs/reference/generator/client-java-asyncapi.md), [client kafkajs](https://apigenie.pl/docs/reference/generator/client-kafkajs.md), [client python](https://apigenie.pl/docs/reference/generator/client-python-asyncapi.md), [client ws](https://apigenie.pl/docs/reference/generator/client-ws.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet-asyncapi.md), [server faststream](https://apigenie.pl/docs/reference/generator/server-faststream.md), [server go](https://apigenie.pl/docs/reference/generator/server-go-asyncapi.md), [server kafkajs](https://apigenie.pl/docs/reference/generator/server-kafkajs.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix-asyncapi.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring-asyncapi.md), [server ws](https://apigenie.pl/docs/reference/generator/server-ws.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-protobuf.md), [server elixir-grpc](https://apigenie.pl/docs/reference/generator/server-elixir-grpc.md), [server absinthe](https://apigenie.pl/docs/reference/generator/server-absinthe.md).

`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

```sh
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](#swagger-20-input)).
`server absinthe` reads a GraphQL schema (`.graphql`, `.graphqls` or `.gql`).

Every code generator takes `-c, --config` (a configuration file, see
[Configuration](/docs/reference/cli/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`](/docs/reference/cli/convert) does, and generate from the
result. The `convert` command is [experimental](/docs/reference/cli#experimental-commands): the
converted document can change between releases, while the code generated from it follows the
[compatibility](/docs/reference/cli/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`](/docs/reference/cli/bundle).

For example, with two definitions extending `Pet`:

```yaml
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`:

```ts
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](/docs/reference/generator/conformance) 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](/samples/carpet-express.openapi-31.yaml) and
[AsyncAPI 3.0 definition](/samples/carpet-express.asyncapi.yaml) 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](/docs/reference/generator/conformance) 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](/docs/reference/generator/conformance#tiers), 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](/docs/reference/generator/server-mcp) is a Tier 2 target labelled experimental,
because MCP and its SDK are still changing. The [Zod generator](/docs/reference/generator/schema-zod),
the [Rust client](/docs/reference/generator/client-rust) and the
[axum server](/docs/reference/generator/server-axum) are experimental: they have no Level 3
contract tests yet.

## Overlays

Every target reading OpenAPI or AsyncAPI documents takes `--overlay FILE`: an
[OpenAPI Overlay](/docs/reference/cli/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](/docs/reference/cli/extensions) lists them all) can then live in an overlay of that target instead of in the API description:

```sh
apigenie-generator server spring openapi.yaml --overlay spring.overlay.yaml -o server
```

- The overlays listed under `commands.generate.<target>.overlay` in the
  [configuration file](/docs/reference/cli/configuration#commandsgenerate), 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`](/docs/reference/cli/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:

```sh
apigenie-generator client fetch openapi.yaml -o client --check
```

```text
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](/docs/guides/generate-a-client-and-a-server#check-the-generated-code-in-ci)
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](/docs/reference/cli#exit-status) 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](/docs/reference/cli#experimental-commands).

## From OpenAPI

### Clients

| Name | Summary |
| ---- | ------- |
| [client csharp](/docs/reference/generator/client-csharp) | C# client for `HttpClient` (.NET 8) |
| [client elixir](/docs/reference/generator/client-elixir) | Elixir client on Req |
| [client fetch](/docs/reference/generator/client-fetch) | TypeScript client for the Fetch API |
| [client go](/docs/reference/generator/client-go) | Go client for `net/http` |
| [client java](/docs/reference/generator/client-java) | Java client for Spring `RestClient`, `RestTemplate`, OpenFeign or HTTP interfaces |
| [client python](/docs/reference/generator/client-python) | Python client on httpx and Pydantic |
| [client rust](/docs/reference/generator/client-rust) | Rust client crate on reqwest and serde (experimental) |
| [client swift](/docs/reference/generator/client-swift) | Swift client on URLSession (experimental) |

### Servers

| Name | Summary |
| ---- | ------- |
| [server aspnet](/docs/reference/generator/server-aspnet) | ASP.NET Core server (Minimal APIs) |
| [server axum](/docs/reference/generator/server-axum) | Rust server crate on axum (experimental) |
| [server express](/docs/reference/generator/server-express) | TypeScript Express server |
| [server fastapi](/docs/reference/generator/server-fastapi) | Python FastAPI server |
| [server go](/docs/reference/generator/server-go) | Go `net/http` server |
| [server hummingbird](/docs/reference/generator/server-hummingbird) | Swift server on Hummingbird 2 (experimental) |
| [server mcp](/docs/reference/generator/server-mcp) | MCP server in TypeScript: a tool per operation (experimental) |
| [server orpc](/docs/reference/generator/server-orpc) | TypeScript server on oRPC |
| [server phoenix](/docs/reference/generator/server-phoenix) | Elixir Phoenix 1.7 server |
| [server spring](/docs/reference/generator/server-spring) | Spring Boot server |
| [server vapor](/docs/reference/generator/server-vapor) | Swift server on Vapor 4 (experimental) |

### Documentation and data

| Name | Summary |
| ---- | ------- |
| [docs](/docs/reference/generator/docs) | a documentation site; also from Swagger 2.0, AsyncAPI, GraphQL and Protobuf files, several at once |
| [data](/docs/reference/generator/data) | example data for a schema of the document |

## From AsyncAPI

| Name | Summary |
| ---- | ------- |
| [client csharp](/docs/reference/generator/client-csharp-asyncapi) | C# Kafka client library |
| [client elixir](/docs/reference/generator/client-elixir-asyncapi) | Elixir client library (WebSocket channels on Mint.WebSocket, Kafka on brod) |
| [client go](/docs/reference/generator/client-go-asyncapi) | Go Kafka client package |
| [client java](/docs/reference/generator/client-java-asyncapi) | Java Kafka client library on the Apache Kafka client |
| [client kafkajs](/docs/reference/generator/client-kafkajs) | TypeScript Kafka client on KafkaJS |
| [client python](/docs/reference/generator/client-python-asyncapi) | Python asyncio Kafka client on aiokafka |
| [client ws](/docs/reference/generator/client-ws) | TypeScript WebSocket client |
| [server aspnet](/docs/reference/generator/server-aspnet-asyncapi) | ASP.NET Core Kafka application |
| [server faststream](/docs/reference/generator/server-faststream) | Python FastStream application (Kafka, RabbitMQ, MQTT) |
| [server go](/docs/reference/generator/server-go-asyncapi) | Go Kafka application |
| [server kafkajs](/docs/reference/generator/server-kafkajs) | TypeScript Kafka application on KafkaJS |
| [server phoenix](/docs/reference/generator/server-phoenix-asyncapi) | Elixir Phoenix application (WebSocket channels, Kafka on Broadway and brod) |
| [server spring](/docs/reference/generator/server-spring-asyncapi) | Spring Boot Kafka application |
| [server ws](/docs/reference/generator/server-ws) | Node.js WebSocket server |

## From GraphQL

| Name | Summary |
| ---- | ------- |
| [server absinthe](/docs/reference/generator/server-absinthe) | Elixir Absinthe server of the schema (`import_sdl`) |

## From Protobuf

| Name | Summary |
| ---- | ------- |
| [client elixir](/docs/reference/generator/client-elixir-protobuf) | Elixir gRPC client on elixir-grpc |
| [server elixir-grpc](/docs/reference/generator/server-elixir-grpc) | Elixir gRPC server on elixir-grpc |

## From JSON Schema

| Name | Summary |
| ---- | ------- |
| [schema zod](/docs/reference/generator/schema-zod) | Zod schemas |
