Saltar al contenido principal

3.1-API_DOCUMENTATION_GUIDE

Ver en Git

Guía de Documentación de APIs - Aurapi

Introducción​

Este proyecto utiliza el estándar OpenAPI 3.0 (Swagger) para documentar todas las APIs. La documentación se genera automáticamente desde los docstrings de los métodos de las clases Resource.

Acceso a la Documentación​

Podés acceder a la especificación OpenAPI en:

  • JSON Spec: http://localhost:5000/apispec.json

Formato de Documentación​

Estructura Básica​

Cada método HTTP (GET, POST, PUT, PATCH, DELETE) debe tener un docstring en formato YAML que siga el estándar OpenAPI 3.0:

@exception_handler
def post(self):
    """
    ---
    summary: Breve descripción de la operación
    description: |
      Descripción detallada de lo que hace el endpoint.
      Puede tener múltiples líneas.
    tags:
      - Nombre del Tag/Categoría
    security:
      - bearerAuth: []
    parameters:
      - name: nombre_parametro
        in: query  # o path, header, cookie
        required: true
        schema:
          type: string
        description: Descripción del parámetro
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              campo1:
                type: string
                description: Descripción del campo
              campo2:
                type: integer
                example: 123
    responses:
      200:
        description: Respuesta exitosa
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: integer
                  example: 0
                data:
                  type: object
      400:
        description: Solicitud incorrecta
      401:
        description: No autenticado
      403:
        description: Sin permisos
    """
    # Tu código aquí

Tags Recomendados​

Organizá tus endpoints usando estos tags:

Tags Funcionales​

  • Authentication: Login, logout, tokens
  • Users: Gestión de usuarios
  • Workspaces: Espacios de trabajo
  • Fields: Campos/lotes
  • Farms: Establecimientos
  • Layers: Capas de información
  • Sampling: Muestreos
  • Resources: Recursos (máquinas, personal)
  • Marketplace: Marketplace y extensiones
  • Storage: Almacenamiento
  • Reports: Reportes
  • Analytics: Analíticas

Tag Especial: public_api​

IMPORTANTE: Todos los endpoints que deben ser parte de la documentación pública (Swagger público para desarrolladores externos) DEBEN incluir el tag public_api además de su tag funcional.

Seguridad​

Para endpoints que requieren autenticación:

security:
  - bearerAuth: []

Checklist de Documentación​

Antes de considerar un endpoint documentado, verificá que tenga:

  • Summary claro y conciso
  • Description detallada
  • Tags apropiados
  • Todos los parámetros documentados
  • Request body con schema completo (si aplica)
  • Respuestas 200, 400, 401, 403 documentadas
  • Ejemplos de request/response
  • Indicación de seguridad (si requiere auth)

Herramientas​

Validar Documentación​

Podés validar tu documentación usando:

# Instalar validador
pip install openapi-spec-validator

# Validar spec
openapi-spec-validator http://localhost:5000/apispec.json

Mejores Prácticas​

  1. Sé consistente: Usá los mismos nombres y estructuras en toda la API
  2. Sé descriptivo: Las descripciones deben ser claras y completas
  3. Incluí ejemplos: Facilitan el uso de la API
  4. Documentá errores: Todos los posibles códigos de error
  5. Mantené actualizado: Actualizá la doc cuando cambies el código
  6. Usá schemas reutilizables: Para objetos comunes, definí schemas en components

Soporte​

Para dudas sobre la documentación: