OpenAPI

Resumen

OpenAPI es una especificación para describir APIs HTTP. Con un archivo YAML o JSON documentás todos los endpoints, parámetros, cuerpos de request y response, códigos de estado, esquemas de autenticación y modelos de datos. Ese archivo es la fuente de verdad de tu API.

Importa porque convierte una API de algo que existe solo en el código a algo que cualquier persona o herramienta puede entender sin leer el source. Con una spec OpenAPI podés generar documentación interactiva —Swagger UI—, SDKs en 20 lenguajes, tests automáticos de contrato, y mock servers para desarrollo frontend. Es el estándar de facto para documentar APIs REST.

Alcance y supuestos

Cubre OpenAPI 3.x como estándar de especificación, herramientas del ecosistema y el enfoque spec-first vs code-first. Asume familiaridad con REST.

Modelo mental

El plano de una casa. Si querés saber cuántas habitaciones tiene, no necesitás recorrerla: mirás el plano. Si querés construir un mueble que encaje, usás las medidas del plano. OpenAPI es el plano de tu API: describe todo lo que hay, sin necesidad de leer el código fuente.

Uso práctico

• ✅ Documentación interactiva, generación de clientes, validación de requests.
• ❌ APIs internas que nunca son consumidas fuera del equipo.

Ejemplo trabajado: spec OpenAPI mínima

openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Obtener usuario
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Usuario encontrado

Evidencia

• OpenAPI Initiative, parte de la Linux Foundation, mantiene el estándar. Swagger, Redoc y Stoplight son herramientas del ecosistema.