Configuration

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

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

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 checks a file, and apigenie config schema prints the schema for an editor (see editor support).

openapi

Settings of OpenAPI documents that every command shares.

openapi.custom_formats

API Genie knows the formats of the OpenAPI format registry. 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).

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

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

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.

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.

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.

commands.generate

A section per code generator of apigenie-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 applied to the input before generating, with paths relative to the configuration file. The --overlay arguments apply after them.

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

See also

Was this helpful?