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
See also
- config: Checks a file, and prints the schema.
- Formats: The format registry that
openapi.custom_formatsextends. - Server configuration: The keys of
commands.mock. apigenie-catalog: Writes thecatalogsection.