# apigenie-generator

Source: https://apigenie.pl/docs/reference/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

```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). Swagger 2.0 documents can be converted first with
[`convert --to openapi32`](/docs/reference/cli/convert). `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.

## 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; 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](/docs/reference/generator/client-fetch#limitations).
The experimental [Zod generator](/docs/reference/generator/schema-zod) has no Level 3 contract tests.

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

## 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](/docs/reference/cli/overview#exit-status) shared by the four binaries.
`apigenie generate ...` exits with 2 and prints the `apigenie-generator` command to run instead.
`schema zod` is [experimental](/docs/reference/generator/schema-zod).

## 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 |

### Servers

| Name | Summary |
| ---- | ------- |
| [server aspnet](/docs/reference/generator/server-aspnet) | ASP.NET Core server (Minimal APIs) |
| [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 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 |

### 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 |