# Configuration Source: https://apigenie.pl/docs/reference/cli/configuration Most of API Genie CLI commands use configuration files. This file stores default parameters for API Genie CLI commands specific to your organization. ## Structure Configuration can be stored in JSON or YAML files. Below is a sample illustrating its general structure: ```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: ... commands: format: ... lint: ... diff: ... generate: client_csharp: ... client_elixir: ... client_fetch: ... client_go: ... client_java: ... client_kafkajs: ... client_python: ... client_ws: ... data: ... docs: ... schema_zod: ... server_absinthe: ... server_aspnet: ... server_express: ... server_fastapi: ... server_faststream: ... server_go: ... server_kafkajs: ... server_mcp: ... server_orpc: ... server_phoenix: ... server_spring: ... asyncapi: ... server_ws: ... ... ``` ## 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. ## 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. Use [`apigenie config check`](/docs/reference/cli/config) to check a file, and `apigenie config schema` to print the schema for an editor (see [editor support](/docs/reference/cli/overview#editor-support)). ### openapi This section holds settings which are related to OpenAPI schemas, and do not depend on specific CLI command. ### openapi.custom_formats API Genie knows the formats of the [OpenAPI format registry](https://spec.openapis.org/registry/format/). This section declares the formats your schemas use beyond it, so that they are accepted as they are. If present, this section must be an array of objects. Each object must contain the `name` and `type` properties. `name` specifies the format name, and must be unique within the specification. `type` specifies the JSON Schema type to which the format can be applied (`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/**" specs: - name: orders-api path: apis/orders/openapi.yaml owner: team-commerce ``` | 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. | | `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`. | ### commands This section contains settings for CLI commands. Each command has a dedicated entry in this section, those name mimicks the name of the command. ### commands.format Configuration used by the `format` command. OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files are formatted with its `openapi`, `swagger`, `asyncapi`, `protobuf` and `graphql` sections. For more details, see [format configuration](/docs/reference/cli/format#configuration) section. ### commands.lint Configuration used by the `lint` command. OpenAPI documents are linted with its top-level settings, Swagger 2.0, AsyncAPI, Protobuf and GraphQL files with its `swagger`, `asyncapi`, `protobuf` and `graphql` sections. For more details, see [lint configuration](/docs/reference/cli/lint#configuration) section. ### commands.diff Configuration used by the `diff` and `changelog` commands. AsyncAPI documents are compared with its `asyncapi` section, Protobuf files with its `protobuf` section, Swagger documents with its `swagger` section, and GraphQL files with its `graphql` section. For more details, see [diff configuration](/docs/reference/cli/diff#configuration) section. ### 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 Entries in this section store configuration for specific code generators 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.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_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_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.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) |