ReferenceCLIGetting startedConfiguration
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-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:
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 to check a file, and
apigenie config schema to print the schema for an editor (see
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. 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).
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/**"
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 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
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 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.
commands.generate
Entries in this section store configuration for specific code generators 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