On this page
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.
{
"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/jsonrequest 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
2xxresponse.
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, orhttps://api.example.comwhen there is none; - a bearer token read from an environment variable named after the project id,
ROCKET_API_KEYfor the projectrocket; - the
exampleof the request body, or one built from the schema: each property'sexample, else the firstenumvalue, else"string",0orfalse.
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,patchanddeletemethods are read. - Only
application/jsonrequest and response bodies are shown. $refmust 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.tryItis accepted but not implemented: there is no request console, and the build prints a warning.- A value of
api.languagesother thancurl,goortypescriptgives no sample and no warning.