`api.json`

Path: apis/<api>/api.json

Holds everything about an API that isn't the spec itself: its identity, where to re-import the spec from, the defaults used when creating requests, and the root-level overrides projected into the effective spec.

Example

{
  "version": 1,
  "name": "Swagger Petstore",
  "slug": "petstore-api",
  "baseUrl": "{{baseUrl}}",
  "specSource": {
    "type": "url",
    "url": "https://petstore3.swagger.io/api/v3/openapi.json"
  },
  "defaults": {
    "auth": { "type": "apiKey", "in": "header", "name": "api_key", "value": "{{apiKey}}" },
    "headers": { "Accept": "application/json" }
  },
  "overrides": {
    "info": { "description": "Pet store demo service" }
  }
}

Fields

Field	Type	Required	Description
`version`	`1`	yes	File format version.
`name`	string	yes	Display name.
`slug`	string	yes	URL/path-safe identifier; matches the directory name.
`baseUrl`	string	no	Base URL for requests. Usually a `{{variable}}`; the first import sets it to `{{baseUrl}}`.
`specSource`	object	no	Where to re-import the spec from (see below).
`defaults`	object	no	Templates merged into new request instances (see below).
`overrides`	object	no	Root-level OpenAPI fields projected into the effective spec (e.g. `info`, `servers`, `tags`, `security`).

`specSource`

Two shapes, file or URL:

{ "type": "file", "path": "../../backend/openapi.json" }

{ "type": "url", "url": "https://petstore3.swagger.io/api/v3/openapi.json", "headers": { "Authorization": "Bearer {{apiKey}}" } }

The source is used only when you explicitly import. Nothing fetches it in the background, so the project stays self-contained.

`defaults`

A template applied when an instance is created, not inherited at run time. Changing it later doesn't touch existing instances.

Field	Type	Description
`auth`	object	Default auth: `bearer`, `apiKey` or `custom` (see request instance).
`headers`	object	Default headers (name → value).
`cookies`	object	Default cookies (name → value).
`middlewares`	object	Default `before`/`after` chains, same shape as on a request instance, `options` included.

The first import fills baseUrl and defaults.auth from the spec's servers and securitySchemes; see what the first import sets up. Re-imports leave both alone.

When an instance is created, the chains from the API, resource and operation defaults are concatenated (first occurrence of a function fixes its position); its options and enabled flag come from the most specific level that lists it.