Skip to content

How to document a new endpoint

Documentation is generated automatically when running mkdocs serve or mkdocs build. There is no need to edit any .md file. Just follow this guide when writing the code.

Complete flow

1. Create the function in the corresponding endpoints module
         ↓
2. Register the router in the main routes file
         ↓
3. Run mkdocs serve → the doc appears automatically

Endpoint template

Copy this block as a starting point for any new endpoint:

@router.get(
    "/my-resource/{resource_id}",
    summary="A short phrase (appears in the doc header)",
)
async def my_endpoint(
    resource_id: str,
    user: Annotated[dict, Depends(get_current_user)],
    filter: Annotated[str | None, Query(description="Filter description")] = None,
    limit: Annotated[int, Query(ge=1, le=1000, description="Result limit")] = 100,
) -> MyResponseSchema:
    """
    Introductory paragraph: what this endpoint does in 1-2 sentences.

    ### Authentication:
    Requires bearer token. The id_company is extracted automatically from the token.

    ### Parameters:
    - **resource_id**: UUID of the requested resource.
    - **filter**: Optional search text (case-insensitive).
    - **limit**: Maximum results returned (1–1000).

    ### Response:
    Returns `MyResponseSchema` with fields X, Y, Z.

    ### Usage example:
    ```http
    GET /api/v1/my-resource/uuid-123?filter=text&limit=50
    Authorization: Bearer <token>
    ```
    """
    ...

What the automatic documentation extracts

Code element What it generates in the doc
summary= in the decorator Bold title under the badge + path
Function docstring Full description section (supports Markdown)
Query(description=...) "Description" column in the parameters table
ge=, le= in Query Reflected in the type (integer, range)
Return type (-> MySchema) "Response" column with the model name
tags= in the router Groups the endpoint in its own doc page

Register the router

In the main routes file, include the new router:

from <package>.endpoints import my_module

router.include_router(
    my_module.router,
    prefix="/my-resource",
    tags=["My Resource"],   # ← This value creates a new page in the doc
)

One tag = one page

Each unique value in tags= automatically generates a new page in the Reference section of the documentation site. There is no need to touch mkdocs.yml.

Docstring conventions

Allowed header levels

Inside the docstring, use ### (level 3) and below. Levels # and ## are reserved for the generator.

### Authentication:
### Parameters:
### Response:
### Use cases:
### Usage example:

Parameter list format

- **param_name**: Clear description of the parameter.

Verify the result

Run the local documentation server (check the repository README for the exact command) and navigate to Reference → Your Tag. The server has hot-reload: save the .py file and the doc updates in seconds.