4. Documenting an API

This chapter demonstrates the template’s most powerful feature: generating a complete REST API reference automatically from an OpenAPI specification. You write the API once, as a standard OpenAPI (Swagger) file, and the endpoints, parameters, request and response schemas, and examples are rendered for you.

This is why the template is built on Sphinx rather than plain Markdown — no Markdown toolchain offers this.

4.1. How it works

  1. Put your OpenAPI 3.0 file in the yaml/ folder (see yaml/example.yaml for a minimal, complete example you can copy).

  2. Create one page per interface that points at the file (see chapter4/interface1.rst). Copy it for each additional API.

  3. List those pages in the toctree below so each gets its own page in the navigation sidebar.

The example interface on the next page is generated entirely from yaml/example.yaml — edit that file and the documentation follows.

4.2. Example Interface

This is version 1.0.0 of this interface.

Get the OpenAPI file: example.yaml

4.2.1. Services

4.2.1.1. default

GET /v1/items

Retrieve the list of items.

Scope required: items.read

Query Parameters:

  • limit (integer) – Maximum number of items to return.

Status Codes:

Example request:

GET /v1/items?limit=1 HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "1",
        "name": "First item"
    },
    {
        "id": "2",
        "name": "Second item"
    }
]

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "code": "string",
    "message": "string"
}
POST /v1/items

Create a new item.

Scope required: items.write

Form Parameters:

  • body – The item to create.

Status Codes:

Example request:

POST /v1/items HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id": "3",
    "name": "New item"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "string",
    "name": "string"
}

Example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "code": "string",
    "message": "string"
}