OpenAPI como Contrato

Audiencia

Esta guia es para desarrolladores y arquitectos que quieren entender el valor estrategico de OpenAPI:

• Desarrolladores backend que construyen APIs y quieren establecer contratos claros con los consumidores
• Desarrolladores frontend que consumen APIs y necesitan especificaciones fiables y legibles por maquinas
• Arquitectos de API que disenan sistemas donde multiples equipos deben integrarse
• Lideres tecnicos evaluando si adoptar desarrollo specification-first
• Cualquiera que haya experimentado el dolor de APIs sin documentar o inconsistentes

Deberias entender como funcionan las APIs REST y la semantica HTTP. Esta guia se enfoca en el “por que” de OpenAPI, no en el “como” escribir especificaciones complejas.

Objetivo

Despues de leer esta guia, entenderas:

• Que es OpenAPI y de donde viene (de Swagger a OpenAPI)
• Por que una especificacion de API es un contrato, no solo documentacion
• La diferencia entre enfoques design-first y code-first
• Que puedes expresar en un documento OpenAPI
• Que habilita una buena especificacion: generacion de codigo, validacion, testing, mocking
• La diferencia critica entre documentar y definir una API
• Por que las especificaciones se desactualizan y como prevenirlo

Esta guia construye comprension—sabras cuando y por que usar OpenAPI. Para escribir especificaciones complejas, consulta el curso proximo.

1. El Problema: APIs Sin Contratos

Imagina que estas integrando con una API externa. Recibes un PDF con descripciones de endpoints. Algunos campos estan documentados, otros no. Haces suposiciones, escribes codigo y lo despliegas. Dos semanas despues, la API devuelve un formato de respuesta diferente. Tu integracion se rompe.

Que salio mal? No habia contrato.

El Dolor de los Contratos Implicitos

Sin una especificacion formal, el “contrato” entre proveedor y consumidor de la API es implicito:

graph TD
    A[Proveedor escribe codigo] --> B[Proveedor escribe docs manualmente]
    B --> C[Docs se desactualizan]
    C --> D[Consumidor hace suposiciones]
    D --> E[Integracion se rompe]
    E --> F[Comienza el juego de culpas]
    style C fill:#ffccbc
    style E fill:#ffccbc

Sintomas comunes de no tener contrato:

1. Deriva de documentacion: Los docs dicen una cosa, la API hace otra
2. Conocimiento tribal: “Ah, ese campo en realidad es requerido los martes”
3. Miedo al cambio: Nadie toca la API porque nadie sabe que podria romperse
4. Ruleta de integracion: Cada consumidor descubre casos borde por las malas

Que Deberia Proveer un Contrato

Un contrato de API apropiado deberia ser:

• Legible por maquinas: Las herramientas pueden parsearlo, no solo humanos
• Autoritativo: Es la unica fuente de verdad
• Versionado: Los cambios se rastrean y comunican
• Testeable: Puedes verificar que la API coincide con el contrato

OpenAPI provee todo esto.

2. Que es OpenAPI (Y Que No Es)

OpenAPI es un formato de especificacion para describir APIs REST. Es una forma estructurada de definir:

• Que endpoints existen
• Que parametros aceptan
• Que respuestas devuelven
• Que esquemas de datos usan

Una Breve Historia: De Swagger a OpenAPI

2011: Swagger fue creado por Tony Tam en Wordnik como una forma simple de documentar APIs REST.

2015: SmartBear adquirio Swagger y lo dono a la Linux Foundation.

2016: Swagger Specification se convirtio en OpenAPI Specification (OAS) bajo la OpenAPI Initiative, con respaldo de Google, Microsoft, IBM y otros.

Hoy: OpenAPI 3.x es el estandar de la industria, con la version 3.1 alineada con JSON Schema.

timeline
    title De Swagger a OpenAPI
    2011 : Swagger creado en Wordnik
    2015 : SmartBear adquiere Swagger
    2016 : Se funda OpenAPI Initiative
    2017 : OpenAPI 3.0 lanzado
    2021 : OpenAPI 3.1 lanzado (alineacion con JSON Schema)

Distincion clave: “Swagger” ahora se refiere a las herramientas de SmartBear (Swagger Editor, Swagger UI). “OpenAPI” es la especificacion en si. Cuando la gente dice “spec de Swagger”, usualmente se refieren a OpenAPI.

Lo Que OpenAPI NO Es

OpenAPI no es:

• Un framework de runtime: No ejecuta tu API
• Un protocolo: Describe APIs HTTP, no reemplaza HTTP
• Solo para documentacion: Es fuente de verdad para generacion de codigo, testing, validacion
• Obligatorio: Puedes construir APIs sin el, pero pierdes beneficios significativos

Piensa en OpenAPI como el plano de tu API. Asi como un plano de edificio no es el edificio en si, OpenAPI no es tu API—es la descripcion autoritativa de lo que tu API deberia ser.

3. La Spec Como Contrato

Aqui esta el cambio de mentalidad crucial: Una especificacion OpenAPI no es documentacion. Es un contrato.

Documentacion vs. Especificacion

Por Que Esta Distincion Importa

Cuando tratas una especificacion como documentacion, se convierte en:

• Algo que actualizas “cuando tienes tiempo”
• Un nice-to-have que deriva de la realidad
• No confiable para consumidores

Cuando la tratas como contrato, se convierte en:

• La unica fuente de verdad
• Automaticamente forzada (via validacion, testing)
• Una promesa que debes cumplir

La Analogia del Contrato

Piensa en comprar una casa. El contrato especifica:

• Que estas comprando (direccion, metros cuadrados)
• En que condicion esta (resultados de inspeccion)
• Que pasa si alguna parte rompe el acuerdo

Un contrato de API funciona igual:

• Que endpoints existen
• Que datos aceptan y devuelven
• Que pasa cuando las cosas salen mal (respuestas de error)

Si cambias el contrato, todas las partes deben acordar. Si rompes el contrato, hay consecuencias (integraciones rotas).

graph LR
    subgraph "Proveedor de API"
        A[Spec OpenAPI]
        B[Implementacion API]
    end
    subgraph "Consumidor de API"
        C[Codigo Cliente]
        D[Expectativas]
    end
    A -->|"Define"| B
    A -->|"Contrato"| D
    D -->|"Guia"| C
    C -->|"Llama"| B
    style A fill:#e3f2fd

4. Design-First vs. Code-First

Hay dos enfoques para crear una especificacion de API: design-first y code-first. Ninguno es universalmente mejor—son herramientas para diferentes situaciones.

Enfoque Design-First

Escribe la especificacion antes de escribir codigo.

graph LR
    A[Disenar Spec OpenAPI] --> B[Revisar con stakeholders]
    B --> C[Generar stubs de servidor]
    C --> D[Implementar logica de negocio]
    D --> E[Validar contra spec]
    style A fill:#c8e6c9

Beneficios:

• Te obliga a pensar en el contrato de API por adelantado
• Habilita desarrollo paralelo (backend y frontend pueden empezar simultaneamente)
• Detecta problemas de diseno temprano, antes de escribir codigo
• La spec siempre es autoritativa

Cuando usar:

• APIs publicas donde los breaking changes son costosos
• Proyectos multi-equipo donde los consumidores necesitan visibilidad temprana
• APIs donde la calidad del diseno es critica

Flujo de ejemplo:

1. Disenador de API crea openapi.yaml
2. Equipo frontend genera tipos TypeScript y servidor mock
3. Equipo backend genera stubs de servidor e implementa handlers
4. Ambos equipos trabajan en paralelo contra el mismo contrato

Enfoque Code-First

Escribe codigo primero, genera la especificacion desde el codigo.

graph LR
    A[Escribir codigo API] --> B[Agregar anotaciones/decoradores]
    B --> C[Generar spec OpenAPI]
    C --> D[Publicar documentacion]
    style A fill:#fff9c4

Beneficios:

• Mas rapido para APIs simples
• Spec siempre en sincro con codigo (por definicion)
• Desarrolladores se mantienen en territorio familiar (codigo, no YAML)

Cuando usar:

• APIs internas con requerimientos flexibles
• Prototipado rapido donde el diseno aun esta evolucionando
• Equipos mas comodos con codigo que con lenguajes de especificacion

Flujo de ejemplo:

1. Desarrollador escribe endpoints Express/FastAPI/Spring
2. Anotaciones describen parametros, respuestas, esquemas
3. Proceso de build genera openapi.json
4. Swagger UI muestra la spec generada

La Realidad Hibrida

La mayoria de equipos terminan en algun punto intermedio:

• Empiezan con una spec design-first aproximada para endpoints criticos
• Usan code-first para APIs internas o menos criticas
• Fuerzan sincronizacion spec-codigo a traves de CI/CD

La clave es consistencia: Cualquier enfoque que elijas, la spec debe coincidir con la implementacion. Si derivan una de otra, has roto el contrato.

5. Que Contiene un Documento OpenAPI

Un documento OpenAPI tipicamente se escribe en YAML o JSON. Esto es lo que contiene a alto nivel:

Estructura Principal

openapi: 3.1.0                    # Version de spec
info:                             # Metadatos de API
  title: API de Gestion de Usuarios
  version: 1.0.0
  description: Gestiona cuentas de usuario

servers:                          # Donde vive la API
  - url: https://api.example.com/v1
    description: Servidor de produccion

paths:                            # Endpoints
  /users:
    get:
      summary: Listar todos los usuarios
      responses:
        '200':
          description: Lista de usuarios

  /users/{id}:
    get:
      summary: Obtener usuario por ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer

components:                       # Definiciones reutilizables
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Que Puedes Expresar

1. Endpoints y Metodos

paths:
  /users:
    get:                          # GET /users
      summary: Listar usuarios
    post:                         # POST /users
      summary: Crear usuario
  /users/{id}:
    get:                          # GET /users/{id}
      summary: Obtener usuario
    put:                          # PUT /users/{id}
      summary: Reemplazar usuario
    delete:                       # DELETE /users/{id}
      summary: Eliminar usuario

2. Parametros (path, query, header)

parameters:
  - name: id
    in: path                      # /users/{id}
    required: true
    schema:
      type: integer
  - name: limit
    in: query                     # ?limit=10
    schema:
      type: integer
      default: 20
  - name: Authorization
    in: header                    # Authorization: Bearer ...
    required: true
    schema:
      type: string

3. Cuerpos de Request

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - name
          - email
        properties:
          name:
            type: string
          email:
            type: string
            format: email

4. Respuestas (exito y error)

responses:
  '200':
    description: Exito
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
  '400':
    description: Entrada invalida
  '404':
    description: Usuario no encontrado
  '500':
    description: Error del servidor

5. Esquemas Reutilizables (components)

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        createdAt:
          type: string
          format: date-time

Un Ejemplo Completo Minimo

Aqui hay un documento OpenAPI real y completo para una API de usuarios simple:

openapi: 3.1.0
info:
  title: API Simple de Usuarios
  version: 1.0.0

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

paths:
  /users:
    get:
      summary: Listar todos los usuarios
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Una lista de usuarios
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

    post:
      summary: Crear un usuario
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: Usuario creado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Entrada invalida

  /users/{userId}:
    get:
      summary: Obtener un usuario por ID
      operationId: getUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: El usuario
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Usuario no encontrado

components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: integer
          example: 123
        name:
          type: string
          example: "Alice Smith"
        email:
          type: string
          format: email
          example: "[email protected]"
        createdAt:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email

Este documento de 80 lineas describe completamente una API con tres operaciones. Es legible tanto por humanos como por maquinas.

6. Que Habilita una Buena Spec

Una especificacion OpenAPI bien escrita desbloquea todo un ecosistema de automatizacion:

graph TD
    A[Spec OpenAPI] --> B[Documentacion]
    A --> C[Generacion de Codigo]
    A --> D[Validacion]
    A --> E[Testing]
    A --> F[Mocking]
    A --> G[Config de Gateway]
    style A fill:#e3f2fd
    style B fill:#c8e6c9
    style C fill:#c8e6c9
    style D fill:#c8e6c9
    style E fill:#c8e6c9
    style F fill:#c8e6c9
    style G fill:#c8e6c9

1. Generacion de Documentacion

Genera documentacion hermosa e interactiva automaticamente:

• Swagger UI: Explorador de API interactivo
• Redoc: Documentacion limpia y personalizable
• Stoplight: Portal de documentacion completo

No mas actualizar docs manualmente. Cambia la spec, regenera los docs.

2. Generacion de Codigo

Genera librerias cliente y stubs de servidor en cualquier lenguaje:

• openapi-generator: 50+ lenguajes (TypeScript, Python, Go, Java, etc.)
• SDKs de Cliente: Clientes type-safe para consumidores
• Stubs de Servidor: Handlers con tipos ya definidos

Ejemplo: Desde una spec, genera un cliente TypeScript, cliente Python y servidor Go.

3. Validacion de Request/Response

Valida que requests y responses coincidan con la spec:

• Validacion en runtime: Rechaza requests que no coinciden con el esquema
• Validacion en desarrollo: Detecta discrepancias antes del deploy
• Contract testing: Verifica que la API coincide con la spec en CI/CD

4. Servidores Mock

Genera servidores mock que devuelven respuestas realistas:

• Prism: Servidor mock desde OpenAPI
• Stoplight: Mocking hosteado
• Desarrollo paralelo: Frontend puede trabajar antes de que el backend este listo

5. Testing

Usa la spec para dirigir el testing:

• Contract testing: Verifica que el proveedor cumple las expectativas del consumidor
• Fuzz testing: Genera casos borde desde los esquemas
• Integration testing: Generacion automatica de tests

6. Configuracion de API Gateway

Configura gateways directamente desde la spec:

• AWS API Gateway: Importa OpenAPI para crear APIs
• Kong: Genera configuracion desde spec
• Apigee: Sincroniza spec con politicas del gateway

La Unica Fuente de Verdad

Todas estas herramientas leen de la misma spec. Cuando actualizas la spec:

• La documentacion se actualiza automaticamente
• Las librerias cliente pueden regenerarse
• Las reglas de validacion cambian
• Los mocks devuelven nuevas respuestas

Este es el poder de un contrato: un cambio se propaga a todas partes.

7. El Ecosistema de Herramientas

OpenAPI tiene un rico ecosistema de herramientas. Aqui estan las categorias que deberias conocer:

Editores y Validadores

Generadores de Documentacion

Generadores de Codigo

Servidores Mock

Validacion y Testing

El ecosistema es maduro. Lo que sea que necesites hacer con una API, probablemente hay una herramienta que lee OpenAPI.

8. Por Que las Especificaciones Se Rompen (Y Como Prevenirlo)

Incluso con las mejores intenciones, las especificaciones de API derivan de la realidad. Aqui esta el por que y como prevenirlo.

Por Que Ocurre la Deriva

graph TD
    A[Spec creada] --> B[Codigo escrito]
    B --> C[Fix rapido desplegado]
    C --> D[Spec no actualizada]
    D --> E[Otro cambio]
    E --> F[Spec olvidada]
    F --> G[Spec es ficcion]
    style D fill:#ffccbc
    style F fill:#ffccbc
    style G fill:#ffccbc

Causas comunes:

1. “Actualizare la spec despues”: No lo haras.
2. Sin enforcement: Spec es opcional, codigo es requerido
3. Propiedad separada: Spec mantenida por equipo diferente al del codigo
4. Sin automatizacion: Procesos manuales se olvidan

Estrategias de Prevencion

1. Validacion Automatizada en CI/CD

Agrega validacion de spec a tu pipeline de build:

# Ejemplo de GitHub Actions
- name: Validar que API coincide con spec
  run: |
    # Iniciar servidor API
    npm run start:test &
    sleep 5
    # Validar que respuestas coinciden con spec
    prism validate openapi.yaml --errors

Si la API no coincide con la spec, el build falla. Sin excepciones.

2. Design-First con Codigo Generado

Genera stubs de servidor desde la spec. La spec literalmente se convierte en el codigo:

openapi-generator generate -i openapi.yaml -g nodejs-express-server -o ./src

Cambios a la API requieren cambios a la spec primero.

3. Contract Testing

Usa herramientas como Pact para verificar que las expectativas del consumidor coinciden con el comportamiento del proveedor:

• Consumidor define expectativas (desde spec)
• Proveedor verifica que las cumple
• Discrepancias hacen fallar el build

4. Spec como Requerimiento de Code Review

Trata cambios de spec como cambios de codigo:

• Spec vive en el mismo repo que el codigo
• PRs deben incluir actualizaciones de spec
• Code review incluye review de spec

5. Versiona Tu Spec

Rastrea versiones de spec junto con versiones de API:

info:
  title: API de Usuarios
  version: 2.1.0  # Coincide con version de API

Cuando la version de API cambia, la version de spec cambia.

La Regla de Oro

La spec no es documentacion. Es la fuente de verdad.

Si la spec dice que la API devuelve { "id": integer } y el codigo devuelve { "id": "string" }, el codigo esta mal, no la spec.

Este cambio de mentalidad es lo que separa a equipos que mantienen specs utiles de equipos que las abandonan.

9. Consideraciones del Mundo Real

Cuando NO Usar OpenAPI

OpenAPI no siempre es la eleccion correcta:

• APIs GraphQL: Usa el propio lenguaje de esquema de GraphQL
• gRPC: Usa Protocol Buffers
• APIs verdaderamente internas: Donde el overhead de documentacion excede el beneficio
• Prototipado rapido: Cuando el diseno cambia cada hora

Cuando OpenAPI Brilla

• APIs publicas: Los consumidores necesitan contratos confiables
• Desarrollo multi-equipo: Frontend/backend/mobile necesitan alinearse
• Companias API-first: La API es el producto
• Industrias reguladas: Los contratos proveen audit trails

Empieza Simple

No necesitas una spec perfecta desde el dia uno. Empieza con:

1. Endpoints y metodos
2. Esquemas basicos de request/response
3. Respuestas de error comunes

Agrega detalle incrementalmente. Una spec simple que se mantiene es mejor que una spec compleja que se abandona.

Que Sigue

Esta guia explico por que OpenAPI importa y que habilita. Entiendes:

• OpenAPI como contrato, no solo documentacion
• Enfoques design-first vs. code-first
• Que pueden expresar las especificaciones
• El ecosistema de herramientas
• Como prevenir la deriva de specs

Para temas mas profundos como:

• Escribir esquemas complejos con composicion y herencia
• Usar OpenAPI para definiciones de seguridad (OAuth, API keys)
• Integrar specs con API gateways y pipelines de testing
• Patrones avanzados para diseno de APIs a gran escala

Consulta el curso proximo: OpenAPI 3 Aplicado a Desarrollo y Seguridad.

Terminos de Vocabulario Relacionados

Profundiza tu comprension:

• OpenAPI - El formato de especificacion para APIs REST
• Documentacion de API - Describir APIs para humanos
• Especificacion de API - Definiciones formales de API
• Swagger - El ecosistema de herramientas alrededor de OpenAPI
• JSON Schema - Vocabulario de validacion de datos usado por OpenAPI
• REST - El estilo arquitectonico que OpenAPI describe
• Metodos HTTP - GET, POST, PUT, DELETE en especificaciones
• Codigos de Estado HTTP - Codigos de respuesta en OpenAPI