Cómo documentar un nuevo endpoint

La documentación se genera automáticamente al ejecutar mkdocs serve o mkdocs build. No es necesario editar ningún archivo .md. Solo sigue esta guía al escribir el código.

Flujo completo

1. Crea la función en el módulo correspondiente de endpoints
         ↓
2. Registra el router en el archivo de rutas principal
         ↓
3. Ejecuta mkdocs serve → la doc aparece sola

Plantilla de endpoint

Copia este bloque como punto de partida para cualquier endpoint nuevo:

@router.get(
    "/mi-recurso/{recurso_id}",
    summary="Una frase corta (aparece en la cabecera de la doc)",
)
async def mi_endpoint(
    recurso_id: str,
    user: Annotated[dict, Depends(get_current_user)],
    filtro: Annotated[str | None, Query(description="Descripción del filtro")] = None,
    limit: Annotated[int, Query(ge=1, le=1000, description="Límite de resultados")] = 100,
) -> MiResponseSchema:
    """
    Párrafo introductorio: qué hace este endpoint en 1-2 frases.

    ### Autenticación:
    Requiere bearer token. El id_company se extrae automáticamente del token.

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

    ### Respuesta:
    Retorna `MiResponseSchema` con los campos X, Y, Z.

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

Qué extrae la documentación automática

Elemento en el código	Qué genera en la doc
`summary=` en el decorador	Título en negrita bajo el badge + path
Docstring de la función	Sección de descripción completa (soporta Markdown)
`Query(description=...)`	Columna "Descripción" en la tabla de parámetros
`ge=`, `le=` en `Query`	Se refleja en el tipo (`integer`, rango)
Tipo de retorno (`-> MiSchema`)	Columna "Respuesta" con el nombre del modelo
`tags=` en el router	Agrupa el endpoint en su propia página de la doc

Registrar el router

En el archivo de rutas principal, incluye el nuevo router:

from <paquete>.endpoints import mi_modulo

router.include_router(
    mi_modulo.router,
    prefix="/mi-recurso",
    tags=["Mi Recurso"],   # ← Este valor crea una nueva página en la doc
)

Un tag = una página

Cada valor único en tags= genera automáticamente una nueva página en la sección Referencia del sitio de documentación. No hace falta tocar mkdocs.yml.

Convenciones de docstring

Niveles de header permitidos

Dentro del docstring, usa ### (nivel 3) en adelante. Los niveles # y ## están reservados para el generador.

Secciones recomendadas

### Autenticación:
### Parámetros:
### Respuesta:
### Casos de uso:
### Ejemplo de uso:

Formato de lista de parámetros

- **nombre_param**: Descripción clara del parámetro.

Verificar el resultado

Ejecuta el servidor de documentación local (consulta el README del repositorio para el comando exacto) y navega a Referencia → Tu Tag. El servidor tiene hot-reload: guarda el archivo .py y la doc se actualiza en segundos.