# API reference

Generate one page per operation from an OpenAPI 3.x file, with parameters, request samples and a response example.

A section of kind `api` gets one page per operation of an OpenAPI 3.x file. Markdown pages you put in the same
section folder, such as authentication or errors, come first in the sidebar; the operations follow, grouped by tag.

```json title="project.json"
{
  "nav": {
    "sections": [
      { "id": "guides", "label": "Guides", "kind": "guides" },
      { "id": "api", "label": "API reference", "kind": "api" }
    ]
  },
  "api": {
    "openapi": "openapi.yaml",
    "languages": ["curl", "go", "typescript"]
  }
}
```

`api.openapi` is a YAML or JSON file, relative to the project folder. The file must declare `openapi: 3.x`; Swagger 2.0
files are refused.

## What each page shows

- The method and path, the summary as title and the description as lead.
- Path and query parameters with type, required flag and description.
- Body parameters from the `application/json` request schema. Nested object fields sit behind a toggle.
- A code column that stays in view while you scroll, with one request sample per language and the example of the
  first `2xx` response.

Operations are grouped in the sidebar by their first tag; an operation without tags goes in `default`. The page slug
is the `operationId` in kebab case (`createLaunch` becomes `create-launch`), or the method and path when there is no
`operationId`.

## Request samples

`api.languages` picks the samples, in tab order. Default: `["curl"]`.

| Value | Sample |
|---|---|
| `curl` | A `curl` command with headers and the JSON body. |
| `go` | A `main.go` program with `net/http`. |
| `typescript` | An `index.ts` with `fetch`. |

The samples use:

- the first URL in `servers`, or `https://api.example.com` when there is none;
- a bearer token read from an environment variable named after the project id, `ROCKET_API_KEY` for the project
  `rocket`;
- the `example` of the request body, or one built from the schema: each property's `example`, else the first `enum`
  value, else `"string"`, `0` or `false`.

The response example follows the same rule for the first `2xx` response. When that response has no
`application/json` body, the page shows no response example.

## Descriptions

Descriptions are rendered as Markdown. Raw HTML in them is dropped, and a link with a scheme other than `http`,
`https` or `mailto` loses its target and stays as plain text.

## Translated specs

For each locale, docsp looks for `openapi.<locale>.yaml` next to `openapi.yaml`, for example `openapi.it.yaml`. When
it exists, the API pages of that locale use it; otherwise they use the main file. Keep the paths, methods and
`operationId` values the same in every file, so the pages match across languages.

## Limits

- Only the `get`, `post`, `put`, `patch` and `delete` methods are read.
- Only `application/json` request and response bodies are shown.
- `$ref` must point inside the same file (`#/components/...`). References to other files fail the build.
- Header and cookie parameters are not listed.
- Operation pages exist for the current version only.
- `api.tryIt` is accepted but not implemented: there is no request console, and the build prints a warning.
- A value of `api.languages` other than `curl`, `go` or `typescript` gives no sample and no warning.
