Saltar al contenido principal

3.2-API_DOCUMENTATION_EXAMPLES

Ver en Git

Ejemplos de Documentación de APIs

Este documento contiene ejemplos prácticos de cómo documentar diferentes tipos de endpoints usando OpenAPI 3.0.

Ejemplos por Tipo de Endpoint​

1. GET Simple (sin parámetros)​

@exception_handler
def get(self):
    """
    ---
    summary: Obtener lista de recursos
    description: Retorna todos los recursos disponibles para el usuario
    tags:
      - Recursos
    security:
      - bearerAuth: []
    responses:
      200:
        description: Lista de recursos
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
    """

2. GET con Parámetros de Query​

@exception_handler
def get(self):
    """
    ---
    summary: Buscar usuarios
    description: Busca usuarios según criterios específicos
    tags:
      - Usuarios
    security:
      - bearerAuth: []
    parameters:
      - name: email
        in: query
        required: false
        schema:
          type: string
        description: Email del usuario a buscar
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
        description: Número de página
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
        description: Cantidad de resultados por página
    responses:
      200:
        description: Usuarios encontrados
        content:
          application/json:
            schema:
              type: object
              properties:
                users:
                  type: array
                  items:
                    type: object
                total:
                  type: integer
    """

3. GET con Parámetros de Path​

@exception_handler
def get(self, user_id):
    """
    ---
    summary: Obtener usuario por ID
    description: Retorna la información detallada de un usuario específico
    tags:
      - Usuarios
    security:
      - bearerAuth: []
    parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
        description: ID del usuario
    responses:
      200:
        description: Información del usuario
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                nombre:
                  type: string
                email:
                  type: string
      404:
        description: Usuario no encontrado
    """

4. POST con Request Body​

@exception_handler
def post(self):
    """
    ---
    summary: Crear nuevo usuario
    description: Crea un nuevo usuario en el sistema
    tags:
      - Usuarios
    security:
      - bearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - email
              - password
              - nombre
            properties:
              email:
                type: string
                format: email
                example: usuario@ejemplo.com
              password:
                type: string
                format: password
                minLength: 8
              nombre:
                type: string
                example: Juan
              apellido:
                type: string
                example: Pérez
    responses:
      201:
        description: Usuario creado exitosamente
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: integer
                  example: 0
                user_id:
                  type: integer
                  example: 123
      400:
        description: Datos inválidos
      409:
        description: El usuario ya existe
    """

5. PUT/PATCH para Actualización​

@exception_handler
def patch(self, user_id):
    """
    ---
    summary: Actualizar usuario
    description: Actualiza parcialmente la información de un usuario
    tags:
      - Usuarios
    security:
      - bearerAuth: []
    parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              nombre:
                type: string
              apellido:
                type: string
              telefono:
                type: string
    responses:
      200:
        description: Usuario actualizado
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: integer
                  example: 0
                message:
                  type: string
                  example: Usuario actualizado exitosamente
      404:
        description: Usuario no encontrado
    """

6. DELETE​

@exception_handler
def delete(self, resource_id):
    """
    ---
    summary: Eliminar recurso
    description: Elimina un recurso del sistema
    tags:
      - Recursos
    security:
      - bearerAuth: []
    parameters:
      - name: resource_id
        in: path
        required: true
        schema:
          type: integer
    responses:
      200:
        description: Recurso eliminado
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: integer
                  example: 0
                message:
                  type: string
      404:
        description: Recurso no encontrado
      403:
        description: Sin permisos para eliminar
    """

Tipos de Datos Comunes​

Tipos Básicos​

  • string: Texto
  • integer: Número entero
  • number: Número decimal
  • boolean: true/false
  • array: Lista
  • object: Objeto JSON

Formatos Especiales​

  • format: email: Email válido
  • format: date: Fecha (YYYY-MM-DD)
  • format: date-time: Fecha y hora ISO 8601
  • format: password: Contraseña (oculta en UI)
  • format: uri: URL válida
  • format: uuid: UUID válido

Validaciones​

schema:
  type: string
  minLength: 3
  maxLength: 100
  pattern: '^[a-zA-Z]+$'
  
schema:
  type: integer
  minimum: 0
  maximum: 100
  
schema:
  type: array
  minItems: 1
  maxItems: 10
  items:
    type: string