Como documentar um novo endpoint

A documentação é gerada automaticamente ao executar mkdocs serve ou mkdocs build. Não é necessário editar nenhum arquivo .md. Siga apenas este guia ao escrever o código.

Fluxo completo

1. Crie a função no módulo de endpoints correspondente
         ↓
2. Registre o router no arquivo de rotas principal
         ↓
3. Execute mkdocs serve → a doc aparece automaticamente

Template de endpoint

Copie este bloco como ponto de partida para qualquer novo endpoint:

@router.get(
    "/meu-recurso/{recurso_id}",
    summary="Uma frase curta (aparece no cabeçalho da doc)",
)
async def meu_endpoint(
    recurso_id: str,
    user: Annotated[dict, Depends(get_current_user)],
    filtro: Annotated[str | None, Query(description="Descrição do filtro")] = None,
    limit: Annotated[int, Query(ge=1, le=1000, description="Limite de resultados")] = 100,
) -> MeuResponseSchema:
    """
    Parágrafo introdutório: o que este endpoint faz em 1-2 frases.

    ### Autenticação:
    Requer bearer token. O id_company é extraído automaticamente do token.

    ### Parâmetros:
    - **recurso_id**: UUID do recurso solicitado.
    - **filtro**: Texto de busca opcional (case-insensitive).
    - **limit**: Máximo de resultados retornados (1–1000).

    ### Resposta:
    Retorna `MeuResponseSchema` com os campos X, Y, Z.

    ### Exemplo de uso:
    ```http
    GET /api/v1/meu-recurso/uuid-123?filtro=texto&limit=50
    Authorization: Bearer <token>
    ```
    """
    ...

O que a documentação automática extrai

Elemento no código	O que gera na doc
`summary=` no decorador	Título em negrito abaixo do badge + caminho
Docstring da função	Seção de descrição completa (suporta Markdown)
`Query(description=...)`	Coluna "Descrição" na tabela de parâmetros
`ge=`, `le=` em `Query`	Refletido no tipo (`integer`, intervalo)
Tipo de retorno (`-> MeuSchema`)	Coluna "Resposta" com o nome do modelo
`tags=` no router	Agrupa o endpoint em sua própria página da doc

Registrar o router

No arquivo de rotas principal, inclua o novo router:

from <pacote>.endpoints import meu_modulo

router.include_router(
    meu_modulo.router,
    prefix="/meu-recurso",
    tags=["Meu Recurso"],   # ← Este valor cria uma nova página na doc
)

Uma tag = uma página

Cada valor único em tags= gera automaticamente uma nova página na seção Referência do site de documentação. Não é necessário modificar o mkdocs.yml.

Convenções de docstring

Níveis de header permitidos

Dentro da docstring, use ### (nível 3) em diante. Os níveis # e ## estão reservados para o gerador.

Seções recomendadas

### Autenticação:
### Parâmetros:
### Resposta:
### Casos de uso:
### Exemplo de uso:

Formato de lista de parâmetros

- **nome_param**: Descrição clara do parâmetro.

Verificar o resultado

Execute o servidor de documentação local (consulte o README do repositório para o comando exato) e navegue até Referência → Sua Tag. O servidor tem hot-reload: salve o arquivo .py e a doc é atualizada em segundos.