`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}}`. Not derived from the spec; you set it.
`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` or `apiKey` (see request instance).
`headers`	object	Default headers (name → value).
`cookies`	object	Default cookies (name → value).

baseUrl is not populated by importing a spec; set it yourself, typically to a {{variable}} resolved per environment.

Coming soonMiddlewares in defaults

A middlewares pipeline in defaults is specified but not implemented yet. Today defaults covers auth, headers, and cookies.