Skip to content
docsp
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.

JSONproject.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.
↑ ↓ to move↵ to openSearching docsp