API Genie

apigenie-server reads --config, else apigenie-server.yaml (.yml, .json), then apigenie-mock.yaml (.yml, .json; the name before the rename, still read) or .apigenie.yaml in the current directory, else the shared apigenie.yaml of the project (in the current directory or a parent, up to the root of the repository; see configuration). In a file of its own the settings are at the top level; in a shared configuration they are under commands.mock. The command line wins over the environment variables, which win over the file; apigenie config --for mock --origin shows which one set each value. The JSON Schema of a file of its own is https://apigenie.pl/schemas/apigenie-server-config/latest.json.

version: "1.0"
specs: openapi.yaml
server: {host: 127.0.0.1, port: 4010, base_path: /api, trailing_slash: ignore, watch: true}
                         # strict_base_path: serve the paths only under the prefix (true with base_path)
cors: {enabled: true, origins: ["*"], allow_credentials: true, expose_headers: ["*"], max_age: 600}
responses: {mode: static}
headers: {diagnostics: true}
generation:
  seed: 42
  max_depth: 8
  null_probability: 0
  smart_names: false
  limits: {min_items: 1, max_items: 5, min_length: 1, max_length: 32, min_properties: 0, max_properties: 10, minimum: 0, maximum: 1000}
validation: {request: enforce, response: log, formats: true, unknown_query_parameters: allow}
security:
  mode: check            # off, check (presence) or enforce (the credentials below)
  credentials: {api_keys: {apiKey: [secret]}, bearer_tokens: [token], basic: [{user: u, password: p}]}
request_overrides: {header: true, query_params: true}
simulation: {latency: 100-300, jitter: 20, drop: {probability: 0.01, mode: reset}}
operations:
  getPet: {status: 404}
  GET /pets: {latency: 1000}
stubs: [recorded]          # OpenAPI: recorded exchanges to answer with (--stubs)
scenarios:
  outage:
    description: the backend is down
    rules:
      - match: {tag: pets}
        status: 503
        headers: {Retry-After: "30"}
        body: {title: Service unavailable}
overrides: []
scripts: [mock.mjs]      # relative to the configuration file
scripting: {timeout_ms: 1000, memory_limit_mb: 64, fail_mode: log}
asyncapi:
  server: null           # the one server to serve
  publish: {enabled: true, interval: 1000, count: 0, jitter: 0}
  validate_incoming: enforce   # off, log or enforce
  mqtt_port: 1883        # 8883 when tls.cert serves MQTT over TLS
grpc:
  proto_path: [protos]   # relative to the configuration file
  stubs: [stubs]
  max_message_bytes: 4194304
  reflection: true
  health: true
  validation: {request: enforce, response: log}   # off, log or enforce; both log with --proxy-to unless set here
  generation: true       # false: UNIMPLEMENTED when nothing answers
  proxy: {target: null, mode: fallback, record_dir: null, redact: [authorization, cookie, x-api-key, proxy-authorization]}   # target: HOST:PORT (h2c) or https://host[:port] (TLS)
  history_size: 1000
graphql:
  path: /graphql         # under server.base_path
  introspection: true
  playground: true       # GraphiQL
  schema_endpoint: true  # /graphql/schema.graphql
  allow_get_mutations: false
  lists: {min: 1, max: 3}
  null_probability: 0
  max_depth: 0           # deeper operations are rejected; 0 for no limit
  max_batch: 10
  fields:
    User.email: {faker: internet.email}
    Book.pages: {min: 50, max: 900}
    Status: {values: [OPEN, CLOSED]}
  examples: []           # as the files of examples_files
  examples_files: [more_examples]
  discover_examples: true      # schema_examples/ next to schema.graphql
  store: {enabled: true, max_entities: 10000, unknown_ids: generate}
  subscriptions: {enabled: true, interval: 1000, count: 0, jitter: 0, legacy_protocol: true, init_timeout: 3000}
proxy:                   # OpenAPI, GraphQL: contract testing against a real server (gRPC: grpc.proxy)
  target: http://localhost:8080   # or https://, HOST:PORT, ws:// or wss:// (AsyncAPI); OpenAPI, AsyncAPI: a path is put before the requests' paths,
                                  # AsyncAPI: a list may add an mqtt:// or mqtts:// broker: [ws://localhost:9000, mqtt://localhost:1884]
                                  # GraphQL: the path is the server's endpoint
  unknown_routes: forward         # or reject (404, 405)
  mode: always                    # or fallback: OpenAPI: the mock answers when the server can't be
                                  # reached, times out or answers 404/501 for an operation;
                                  # GraphQL: examples, scenarios, scripts answer first
  schema_check: true              # GraphQL: introspect the server and compare the schemas
  record_dir: null                # OpenAPI: write the exchanges as stub files there;
                                  # GraphQL: write the answers as examples there
  record_har: null                # OpenAPI: write the session as a HAR file
  redact: [authorization, cookie, set-cookie, proxy-authorization, x-api-key]
  timeout_ms: 30000
  connect_timeout_ms: 5000
  max_in_flight: 64
  max_response_bytes: 16777216
contract:
  report: contract.json           # relative to the configuration file
  report_junit: contract.xml
  fail_on: none                   # none, errors or warnings: exit status 5
  min_coverage: 0                 # percent of operations, request bodies and responses (GraphQL: fields; AsyncAPI: messages; gRPC: methods)
  severity: {response.header.undefined: warn, response.status.default: ignore}   # GraphQL's, AsyncAPI's and gRPC's checks too
record:                   # see Session recording; the directory relative to the configuration file
  dir: null               # record the session there from the start (--record); new or empty
  name: null              # the session's name; the directory's when not given
  redact: []              # hidden besides proxy.redact: header names, and JSON pointers (/password) to values of bodies and messages
replay:                   # see Session replay; the directory relative to the configuration file
  dir: null               # answer from the session recorded there (--replay)
  missing: fail           # fail (502 problem), generate (the mock answers) or passthrough (proxy.target answers)
  ignore: []              # not compared besides dates, readOnly fields and volatile headers: header names, JSON pointers (/id, /items/*/id)
  update: false           # with missing: passthrough, record the run and replace the session with it at stop
admin: {enabled: true, path: /__apigenie, port: null, allow_remote: false, log_size: 1000}
log: {level: info, format: stylish, bodies: false, body_limit: 4096, headers: false, file: null}
tls:                      # see TLS; paths relative to the configuration file
  cert: null              # serve HTTPS with this certificate chain and key (both or neither)
  key: null
  client_ca: null         # require client certificates of these authorities (mTLS); needs cert
  ca_certs: []            # trusted for https://, wss:// and mqtts:// upstreams, besides the system's roots
  insecure: false         # don't verify upstream certificates
  client_cert: null       # presented to upstreams that ask for a client certificate (with client_key)
  client_key: null
db:                       # see Document store; paths relative to the configuration file
  crud: explicit          # auto: serve /things and /things/{id} from the store (--crud); explicit: only x-apigenie-mock resources; off
  seed: {notes: seed/notes.json}   # or a directory of <collection>.json/.yaml files: seed, seed/*.json
  generate: 3             # documents generated for a resource's collection nothing else seeds
  max_documents: 10000    # per collection and namespace; 0 for no limit
  file: null              # keep the store across runs (--db-file)

A mistake in the file stops the server with exit status 2, the position and the JSON pointer of the value; an unknown setting is reported with the closest known name.

Configuration