# Configuration

Source: https://apigenie.pl/docs/reference/cli/configuration
See also: [Formats](https://apigenie.pl/docs/reference/cli/formats.md), [Specification extensions](https://apigenie.pl/docs/reference/cli/extensions.md), [faker](https://apigenie.pl/docs/reference/cli/faker.md), [Compatibility](https://apigenie.pl/docs/reference/cli/compatibility.md), [apigenie-mcp](https://apigenie.pl/docs/reference/cli/mcp.md).

One file, `apigenie.yaml`, holds the settings of `apigenie`, `apigenie-generator`, `apigenie-server`
and `apigenie-catalog`: the rules of the linter and the differ, the layout of the formatter, the
specifications of the catalog, the options of every code generator and, for `apigenie-server`, the
document, the address and the rest of what the server needs. The commands find it in the repository
without an option, check it against its JSON Schema before reading it, and run with their defaults
without it.

## Structure

The file is JSON or YAML, with four top-level keys:

| Key        | Holds                                                                                                       | Read by                                       |
| ---------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `version`  | The string `'1.0'`, quoted in YAML, where `1.0` is a number. Required.                                      | `apigenie`, `apigenie-generator`, `apigenie-server`, `apigenie-catalog` |
| `openapi`  | Settings of OpenAPI documents that every command shares: [custom_formats](#openapicustom_formats)           | `apigenie`, `apigenie-server`, `apigenie-generator` |
| `catalog`  | The specifications of the repository and their owners                                                       | `apigenie-catalog`                            |
| `commands` | A section per command: `format`, `lint`, `diff`, `mock` and `generate`, the last with a section per generator | the command                                  |

```yaml
# yaml-language-server: $schema=https://apigenie.pl/schemas/apigenie-config/latest.json
version: '1.0'
openapi:
  custom_formats:
    - name: x-id
      type: integer
catalog:
  specs:
    - name: orders-api
      path: apis/orders/openapi.yaml
      owner: team-commerce
commands:
  format:
    extends: [recommended]
  lint:
    extends: [recommended]
    rules:
      info-defined: off
  diff:
    extends: [recommended]
  mock:
    server:
      port: 4010
  generate:
    server_spring:
      overlay:
        - overlays/spring.overlay.yaml
```

The first line names the schema for editors that read it (see
[editor support](/docs/reference/cli#editor-support)). `apigenie-server` also reads a file of its
own, `apigenie-server.yaml` (or `apigenie-mock.yaml`), with the keys of `commands.mock` at its root
next to `version` and `openapi`; see [server configuration](/docs/reference/server/configuration).

## Where the file is found

When no `--config` is given, `apigenie`, `apigenie-generator`, `apigenie-server` and
`apigenie-catalog` use the first of `apigenie.yaml`, `apigenie.yml`, `apigenie.json`, `.apigenie.yaml`, `.apigenie.yml` and
`.apigenie.json` found in the current directory or one of its parents, stopping at the root of the
Git repository (the directory holding `.git`). `apigenie-server` looks for `apigenie-server.yaml`,
then `apigenie-mock.yaml` (and their variants) in the current directory first.

`--config FILE` uses FILE instead of the file found this way: the two are never merged. `--no-config`
uses no file at all, so the commands run with their defaults.
[Where `apigenie.yaml` is found and how settings merge](/docs/concepts/where-the-configuration-is-found)
explains the lookup, the check that precedes every command and the merging, with examples.

## Validation

Every file is checked against the JSON Schema of the configuration (draft-7) before any command
reads it, whichever command loads it. A setting the schema doesn't know, a value of the wrong type
or one outside its allowed values is an error that names the line, the column and the JSON pointer
of the value, with a suggestion for a misspelled name:

```text
apigenie.yaml:12:7: /commands/lint/rulez: unknown property 'rulez'; did you mean 'rules'?
```

`version` must be the string `'1.0'`: quote it in YAML, where `1.0` is a number. Sections of
commands without settings (`bundle`, `convert`, `overlay`, `i18n`, `test`) are errors too;
`changelog` uses the `diff` section.

[`apigenie config check`](/docs/reference/cli/config) checks a file, and `apigenie config schema`
prints the schema for an editor (see [editor support](/docs/reference/cli#editor-support)).

## openapi

Settings of OpenAPI documents that every command shares.

### openapi.custom_formats

API Genie knows the formats of the
[OpenAPI format registry](https://spec.openapis.org/registry/format/). This section declares the
formats the documents use beyond it, so that they are accepted as they are: an array of objects
with `name`, the format's name, unique in the file, and `type`, the JSON Schema type the format
applies to (`string`, `integer`, `number`, `boolean`, `object` or `array`).

```yaml
openapi:
  custom_formats:
    - {name: currency-code, type: string}
    # the registry's decimal is a string or a number; here it is always a string
    - {name: decimal, type: string}
```

A format of the registry listed here takes the type given and is no longer
checked. `apigenie-server` uses these formats when it validates requests and
responses, and the linters' format rules accept them. The
[Formats](/docs/reference/cli/formats) page lists the registry's formats and
what API Genie does with each.

## catalog

The specifications of the repository's API catalog, for
[`apigenie-catalog`](/docs/reference/catalog), which writes it with `apigenie-catalog init`. Every
setting is optional: specifications found in the repository but not listed here are still in the
catalog, with derived names.

```yaml
catalog:
  exclude:
    - "**/examples/**"
  tags:
    pattern: "{name}-{version}"
  specs:
    - name: orders-api
      path: apis/orders/openapi.yaml
      owner: team-commerce
    - name: legacy-billing
      path: apis/legacy/billing.yaml
      owner: team-finance
      lifecycle: deprecated
      sunset: 2027-03-31
```

| Setting | Description |
| ------- | ----------- |
| `exclude` | Glob patterns of files left out of the catalog, relative to the directory of the configuration file: `*` matches within a directory, `**` across directories. Files ignored by git are always left out. |
| `tags.pattern` | How [`apigenie-catalog release`](/docs/reference/catalog#apigenie-catalog-release) names the Git tag of a release and `apigenie-catalog versions` finds it, with `{name}` and `{version}` each once. Defaults to `{name}-{version}` (`orders-api-1.4.0`); `{name}/v{version}` gives `orders-api/v1.4.0`. Tags made with another pattern are not releases: after a change, `versions` doesn't list them and `release` doesn't check against them. Since 0.12.0. |
| `specs` | One entry per specification file. |
| `specs[].path` | Required. The file, relative to the directory of the configuration file, with `/` separators. |
| `specs[].name` | The name in the catalog, which stays when the file moves: lower-case letters, digits and dashes. Derived from `info.title`, the Protobuf package or the file name when left out. |
| `specs[].owner` | The team or person owning the specification, or `null`. |
| `specs[].lifecycle` | `draft` (still being designed), `active` (the default), `deprecated` (consumers should move away; see `sunset`) or `retired`. `apigenie-catalog list` shows it; `apigenie-catalog release` reads only `retired`, which it refuses. Since 0.12.0. |
| `specs[].sunset` | The day a deprecated specification goes away, as `YYYY-MM-DD`. Since 0.12.0. |

## commands

A section per command, named after it. Every section is optional, and each command reads only its
own; the sections of commands without settings (`bundle`, `convert`, `overlay`, `i18n`, `test`)
are errors.

### commands.format

The settings of the `format` command: the presets of `extends`, and the `openapi`, `swagger`,
`asyncapi`, `protobuf` and `graphql` sections that format each kind of file. See
[format](/docs/reference/cli/format#configuration).

### commands.lint

The settings of the `lint` command: the rulesets and rules of the OpenAPI linter, and the `swagger`,
`asyncapi`, `protobuf` and `graphql` sections of the other linters. See
[lint](/docs/reference/cli/lint#configuration).

### commands.diff

The settings of the `diff` and `changelog` commands: the rules of the OpenAPI differ, and the
`swagger`, `asyncapi`, `protobuf` and `graphql` sections of the other differs. See
[diff](/docs/reference/cli/diff#configuration).

### commands.mock

Configuration of the mock server, `apigenie-server`: the document, the address, responses,
validation, security, network simulation, scenarios, AsyncAPI channels, gRPC services (`grpc`:
proto paths, stub files, limits, reflection, health and the proxy), the validating proxy
(`proxy`, whose `target` may be `https://` or `wss://`), TLS (`tls`: the certificate and key to
serve HTTPS with, `client_ca` to require client certificates, the authorities trusted for
upstreams, `insecure`, and `client_cert` and `client_key` to present to them), scripts, the admin API and
the log. The same keys at
the top level of a file of its own (`apigenie-server.yaml`, or `apigenie-mock.yaml`) work too. For
more details, see [server configuration](/docs/reference/server/configuration).

### commands.generate

A section per code generator of [`apigenie-generator`](/docs/reference/generator), which reads
the file found in the repository or given with `--config`.

Every section of a target of OpenAPI or AsyncAPI documents (not `docs`, `server_absinthe` or
`server_elixir_grpc`) also takes `overlay`: a list of
[overlays](/docs/reference/generator#overlays) applied to the input before generating,
with paths relative to the configuration file. The `--overlay` arguments apply after them.

```yaml
version: '1.0'
commands:
  generate:
    server_spring:
      overlay:
        - overlays/spring.overlay.yaml
```

| Key                                | Configuration details (link)                                                                             |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `commands.generate.data`           | [`apigenie-generator data` configuration](/docs/reference/generator/data#configuration)                     |
| `commands.generate.client_csharp`  | [`apigenie-generator client csharp` configuration](/docs/reference/generator/client-csharp#configuration)   |
| `commands.generate.client_csharp.asyncapi` | [`apigenie-generator client csharp` (AsyncAPI) configuration](/docs/reference/generator/client-csharp-asyncapi#configuration) |
| `commands.generate.client_elixir`  | [`apigenie-generator client elixir` configuration](/docs/reference/generator/client-elixir#configuration)   |
| `commands.generate.client_elixir.asyncapi` | [`apigenie-generator client elixir` (AsyncAPI) configuration](/docs/reference/generator/client-elixir-asyncapi#configuration) |
| `commands.generate.client_elixir.protobuf` | [`apigenie-generator client elixir` (Protobuf) configuration](/docs/reference/generator/client-elixir-protobuf#configuration) |
| `commands.generate.client_fetch`   | [`apigenie-generator client fetch` configuration](/docs/reference/generator/client-fetch#configuration)     |
| `commands.generate.client_go`      | [`apigenie-generator client go` configuration](/docs/reference/generator/client-go#configuration)           |
| `commands.generate.client_go.asyncapi` | [`apigenie-generator client go` (AsyncAPI) configuration](/docs/reference/generator/client-go-asyncapi#configuration) |
| `commands.generate.client_java`    | [`apigenie-generator client java` configuration](/docs/reference/generator/client-java#configuration)       |
| `commands.generate.client_java.asyncapi` | [`apigenie-generator client java` (AsyncAPI) configuration](/docs/reference/generator/client-java-asyncapi#configuration) |
| `commands.generate.client_python`  | [`apigenie-generator client python` configuration](/docs/reference/generator/client-python#configuration)   |
| `commands.generate.client_python.asyncapi` | [`apigenie-generator client python` (AsyncAPI) configuration](/docs/reference/generator/client-python-asyncapi#configuration) |
| `commands.generate.client_rust`    | [`apigenie-generator client rust` configuration](/docs/reference/generator/client-rust#configuration)       |
| `commands.generate.client_swift`   | [`apigenie-generator client swift` configuration](/docs/reference/generator/client-swift#configuration)     |
| `commands.generate.server_express` | [`apigenie-generator server express` configuration](/docs/reference/generator/server-express#configuration) |
| `commands.generate.docs`           | [`apigenie-generator docs` configuration](/docs/reference/generator/docs#configuration)                     |
| `commands.generate.server_fastapi` | [`apigenie-generator server fastapi` configuration](/docs/reference/generator/server-fastapi#configuration) |
| `commands.generate.server_faststream` | [`apigenie-generator server faststream` configuration](/docs/reference/generator/server-faststream#configuration) |
| `commands.generate.server_go`      | [`apigenie-generator server go` configuration](/docs/reference/generator/server-go#configuration)           |
| `commands.generate.server_go.asyncapi` | [`apigenie-generator server go` (AsyncAPI) configuration](/docs/reference/generator/server-go-asyncapi#configuration) |
| `commands.generate.server_hummingbird` | [`apigenie-generator server hummingbird` configuration](/docs/reference/generator/server-hummingbird#configuration) |
| `commands.generate.server_mcp`     | [`apigenie-generator server mcp` configuration](/docs/reference/generator/server-mcp#configuration)         |
| `commands.generate.server_orpc`    | [`apigenie-generator server orpc` configuration](/docs/reference/generator/server-orpc#configuration)       |
| `commands.generate.server_phoenix` | [`apigenie-generator server phoenix` configuration](/docs/reference/generator/server-phoenix#configuration) |
| `commands.generate.server_phoenix.asyncapi` | [`apigenie-generator server phoenix` (AsyncAPI) configuration](/docs/reference/generator/server-phoenix-asyncapi#configuration) |
| `commands.generate.server_elixir_grpc` | [`apigenie-generator server elixir-grpc` configuration](/docs/reference/generator/server-elixir-grpc#configuration) |
| `commands.generate.server_spring`  | [`apigenie-generator server spring` configuration](/docs/reference/generator/server-spring#configuration)   |
| `commands.generate.server_spring.asyncapi` | [`apigenie-generator server spring` (AsyncAPI) configuration](/docs/reference/generator/server-spring-asyncapi#configuration) |
| `commands.generate.server_vapor` | [`apigenie-generator server vapor` configuration](/docs/reference/generator/server-vapor#configuration) |
| `commands.generate.server_absinthe` | [`apigenie-generator server absinthe` configuration](/docs/reference/generator/server-absinthe#configuration) |
| `commands.generate.server_aspnet`  | [`apigenie-generator server aspnet` configuration](/docs/reference/generator/server-aspnet#configuration)   |
| `commands.generate.server_aspnet.asyncapi` | [`apigenie-generator server aspnet` (AsyncAPI) configuration](/docs/reference/generator/server-aspnet-asyncapi#configuration) |
| `commands.generate.server_axum`    | [`apigenie-generator server axum` configuration](/docs/reference/generator/server-axum#configuration)       |
| `commands.generate.client_kafkajs` | [`apigenie-generator client kafkajs` configuration](/docs/reference/generator/client-kafkajs#configuration) |
| `commands.generate.server_kafkajs` | [`apigenie-generator server kafkajs` configuration](/docs/reference/generator/server-kafkajs#configuration) |
| `commands.generate.client_ws`      | [`apigenie-generator client ws` configuration](/docs/reference/generator/client-ws#configuration)           |
| `commands.generate.server_ws`      | [`apigenie-generator server ws` configuration](/docs/reference/generator/server-ws#configuration)           |
| `commands.generate.schema_zod`     | [`apigenie-generator schema zod` configuration](/docs/reference/generator/schema-zod#configuration)         |

## See also

- [config](/docs/reference/cli/config): Checks a file, and prints the schema.
- [Formats](/docs/reference/cli/formats): The format registry that `openapi.custom_formats` extends.
- [Server configuration](/docs/reference/server/configuration): The keys of `commands.mock`.
- [`apigenie-catalog`](/docs/reference/catalog): Writes the `catalog` section.
