OpenAPI con Swagger UI y Redoc: guía práctica

Si la API es interna y solo la consume tu equipo, empieza con code-first. Herramientas como FastAPI, SpringDoc, o tsoa pueden derivar el spec de tus anotaciones, así que el contrato se mantiene cerca del código.

@app.get("/books/{book_id}")
def get_book(book_id: int):
    ...

Si los equipos de frontend, móvil, backend o socios externos necesitan acordar el contrato primero, escribe el YAML de OpenAPI y publícalo en SwaggerHub o Stoplight antes de generar stubs.

openapi-generator-cli generate -i openapi.yaml -g python-fastapi

El riesgo de design-first es el desfase: el spec se convierte en una ilusión mientras el código hace otra cosa. Evítalo con tests de contrato (Schemathesis, Pact) en CI. El riesgo de code-first es filtrar modelos internos; evítalo retornando DTOs, no entidades de base de datos.

Genera el spec en CI desde el código, publícalo en un registry como SwaggerHub o Stoplight, y apunta la documentación desplegada a la última versión. En GitHub Actions.

name: Generate OpenAPI Spec
on: push
jobs:
  spec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python -m app.main --export-openapi > openapi.json
      - run: npx @redocly/cli lint openapi.json
      - run: npx @redocly/cli build-docs openapi.json -o docs/

Ejecuta npx @redocly/cli lint openapi.yaml en cada PR para detectar violaciones de esquema, respuestas faltantes y referencias rotas. Publícalo como artefacto del build, despliega la documentación junto con la API y luego verifica la API contra el spec ejecutando el siguiente comando:

schemathesis run openapi.json --base-url http://localhost:8000

Describe la autenticación en components/securitySchemes y luego aplícala a cada operación. El ejemplo siguiente muestra un esquema Bearer JWT.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Para las API keys, usa type: apiKey e indica en qué header o query las esperas, como en el ejemplo siguiente.

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

OAuth2 requiere declarar el flujo y los scopes permitidos.

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.example.com/oauth/authorize
          tokenUrl: https://api.example.com/oauth/token
          scopes:
            read: Read access
            write: Write access

Una vez definidos los esquemas, añade la entrada security a nivel de operación.

paths:
  /books:
    get:
      security:
        - BearerAuth: []
    post:
      security:
        - OAuth2: [write]

Para tokens JWT en OpenAPI 3.1, sigue usando type: http y scheme: bearer. El tipo apiKey todavía es válido, pero no encaja con bearer tokens, porque describe una clave de API personalizada en lugar de un esquema HTTP bearer.

La versión del spec va en info.version; elige una estrategia de versionado que los clientes puedan descubrir fácilmente.

info:
  title: Book API
  version: 2.1.0

Usa versionado semántico: major para cambios incompatibles, minor para endpoints nuevos y patch para correcciones. Si prefieres versionar por URL, incluye la versión en la URL del servidor.

servers:
  - url: https://api.example.com/v2

El versionado por header se resuelve con un parámetro adicional.

parameters:
  - name: X-API-Version
    in: header
    required: true
    schema:
      type: string
      default: "2"

Para marcar una operación como deprecada, añade deprecated: true y explica la alternativa en la descripción.

paths:
  /books/{id}:
    get:
      deprecated: true
      description: Use /v2/books/{id} instead

Durante los períodos de migración, mantén ambas versiones del spec y deja que el cliente negocie la versión con el header Accept, por ejemplo enviando Accept: application/vnd.api+json;version=2.

Sí. Puedes usar la CLI swagger2openapi o el conversor integrado de Swagger Editor. La mayoría de herramientas modernas maneja 3.0 de forma nativa. Ejecuta npx swagger2openapi swagger.json -o openapi.json y espera algunos cambios mecánicos. host, basePath y schemes se combinan en un array servers; definitions y responses se mueven a components/schemas y components/responses; y securityDefinitions pasa a ser components/securitySchemes. Los campos globales produces y consumes desaparecen; ahora cada operación declara su negociación de contenido en su propio bloque content. Después, valida el resultado con npx @redocly/cli lint openapi.json. Algunos casos extremos, como type: file pasando a format: binary y collectionFormat convirtiéndose en parámetros style y explode, aún requieren ajustes manuales.

OpenAPI 3.1 elimina el antiguo flag nullable: true y en su lugar usa type: [string, null]. Además, exclusiveMinimum y exclusiveMaximum pasan de ser booleanos a números que indican el límite excluido.

minimum: 0
exclusiveMinimum: true

En 3.1, eso pasa a ser exclusiveMinimum: 0. Las subidas binarias cambian de format: binary a contentEncoding: binary, los webhooks obtienen un campo webhooks de nivel superior, y los identificadores de licencia usan SPDX. El campo summary dentro de $ref es opcional, y paths puede estar vacío para APIs que solo usen webhooks.

Antes de migrar, valida el spec con redocly lint y convierte con npx @redocly/cli@latest convert openapi.yaml --to 3.1. La mayoría de herramientas soportan 3.1, pero verifica tu generador y parser primero.

Para subidas de archivos en OpenAPI 3.0, usa format: binary en una propiedad de tipo string dentro del cuerpo de una petición multipart/form-data. Si necesitas varios archivos, cambia la propiedad a un array de cadenas binarias.

En OpenAPI 3.1, format: binary se convierte en contentEncoding: binary. Para descargas, la respuesta debería usar el content type application/octet-stream, lo que significa que también debes declarar un esquema de cadena binaria para el cuerpo de la respuesta. Las imágenes funcionan de la misma forma: declara el tipo de contenido, como image/png, y un esquema binario.

Para limitar el tamaño de subida, añade maxLength al campo binario e indica el límite en la descripción, por ejemplo 10485760 bytes para 10 MB.

Los tipos polimórficos se modelan con las keywords oneOf, anyOf y allOf. El ejemplo siguiente es una unión discriminada.

components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Cat'
      discriminator:
        propertyName: type
        mapping:
          dog: '#/components/schemas/Dog'
          cat: '#/components/schemas/Cat'

Cada subtipo incluye el campo discriminador.

Dog:
  type: object
  properties:
    type:
      type: string
      enum: [dog]
    breed:
      type: string
  required: [type, breed]

Para aceptar tipos mixtos, usa anyOf en lugar de herencia.

PropertyValue:
  anyOf:
    - type: string
    - type: number
    - type: boolean
    - type: array
      items:
        $ref: '#/components/schemas/PropertyValue'

Cuando necesites heredar propiedades sin un discriminador, usa allOf para combinar los esquemas.

Animal:
  allOf:
    - $ref: '#/components/schemas/BaseEntity'
    - type: object
      properties:
        species:
          type: string

Para los errores RFC 7807, usa el media type application/problem+json y un schema Problem reutilizable.

components:
  schemas:
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          default: about:blank
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          format: uri

Después referencia ese schema en las respuestas de error mediante $ref en cada endpoint.

responses:
  '404':
    description: Book not found
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/Problem'
        examples:
          not_found:
            value:
              type: https://api.example.com/errors/not-found
              title: Book not found
              status: 404
              detail: Book with ID 42 not found
              instance: /books/42

Documenta los códigos de error comunes, como 400 para errores de validación, 401 para autenticación faltante, 403 para permisos insuficientes, 409 para conflictos, 422 para fallos semánticos y 429 para limitación de frecuencia.

Redocly y Spectral son los linters que más uso. Con Redocly puedes instalar el CLI globalmente (npm install -g @redocly/cli) y ejecutar redocly lint openapi.yaml. A continuación añade un archivo de reglas sencillo para reforzar tus convenciones.

rules:
  operation-operationId-unique:
    severity: error
  operation-summary:
    severity: warn
    max_length: 50

Spectral funciona de forma similar: instálalo con npm install -g @stoplight/spectral-cli, extiende el ruleset OAS incorporado y personaliza las reglas que te importen. Luego añádelo a GitHub Actions.

- name: Lint OpenAPI
  run: npx @redocly/cli lint openapi.yaml

Valida la estructura del spec: busca operationId faltante, destinos $ref no definidos, esquemas de respuesta faltantes y parámetros de path duplicados. Para corregir problemas comunes ejecuta redocly lint --format=json openapi.yaml | jq '.problems[] | select(.ruleId == "operation-summary")' para filtrar reglas específicas.