OpenAPI para principiantes: escribe tu primer contrato en 20 minutos

Si programas APIs pero nunca te has sentado a escribir un openapi.yaml, es normal que la especificación te suene lejana o demasiado formal. En realidad, OpenAPI no es más que una forma estándar de describir cómo hablar con tu API en un archivo que entienden tanto personas como herramientas.

En este tutorial vas a crear tu primer contrato OpenAPI desde cero, entender qué representa cada bloque y ver cómo ese archivo se convierte automáticamente en documentación navegable. No necesitas conocer todos los detalles de la especificación; con unos pocos conceptos podrás empezar a trabajar de forma mucho más ordenada.

Qué es OpenAPI (explicado en simple)

OpenAPI es un formato para describir APIs HTTP en un archivo (normalmente YAML o JSON). En ese archivo defines cosas como:

Qué endpoints existen (por ejemplo /tasks, /users).
Qué métodos aceptan (GET, POST, etc.).
Qué parámetros esperan (query, path, headers, body).
Qué respuestas devuelven (códigos, modelos de datos, errores).
Cómo se autentica quien llama a la API.

Piensa en ello como un “mapa técnico” de tu API. Ese mapa lo pueden leer humanos, pero también editores visuales, generadores de documentación, generadores de SDKs y herramientas de testing. Por eso tiene tanto sentido invertir unos minutos en definirlo bien: todo lo demás se vuelve más fácil de automatizar.

La anatomía mínima de un archivo OpenAPI

Un archivo openapi.yaml básico suele tener cinco secciones importantes:

openapi: la versión de la especificación que estás usando.
info: información general de tu API (título, descripción, versión).
servers: URLs base donde vive tu API.
paths: las rutas y métodos concretos (/tasks, GET, POST, etc.).
components: modelos reutilizables (por ejemplo, el esquema Task).

A partir de ahí puedes añadir seguridad, parámetros globales, respuestas comunes y muchos otros detalles, pero para empezar no hace falta conocerlo todo. Verás que con una estructura mínima ya puedes describir una API sencilla y visualizarla como documentación.

Tu primera API de ejemplo: API de tareas

Supongamos que quieres documentar una API muy simple con un único endpoint:

GET /tasks: devuelve la lista de tareas.

Vamos a construir el openapi.yaml paso a paso. Primero, la cabecera con la versión, la información básica y el servidor:

openapi: 3.0.3
info:
  title: API de tareas
  version: 1.0.0
  description: API de ejemplo para gestionar tareas
servers:
  - url: https://api.ejemplo.com

Ahora añadimos la ruta /tasks con el método GET y una respuesta 200 que devuelve un array de tareas. Para eso, crearemos también un esquema Task en components.schemas:

openapi: 3.0.3
info:
  title: API de tareas
  version: 1.0.0
  description: API de ejemplo para gestionar tareas
servers:
  - url: https://api.ejemplo.com
paths:
  /tasks:
    get:
      summary: Lista todas las tareas
      description: Devuelve todas las tareas visibles para el usuario autenticado.
      responses:
        '200':
          description: Lista de tareas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: "Comprar leche"
        completed:
          type: boolean
          example: false

Con este fragmento ya estás describiendo:

Que existe un endpoint GET /tasks.
Que devuelve un código 200 con un cuerpo application/json.
Que el cuerpo es un array de objetos Task.
Qué campos tiene Task y de qué tipo es cada uno.

No hemos definido aún autenticación, errores ni otros endpoints, pero ya tienes una base útil para empezar a compartir tu API y generar documentación.

Ver tu spec como documentación visual

Una de las partes más agradecidas de OpenAPI es que puedes pegar tu openapi.yaml en un editor visual y obtener un portal de documentación navegable sin escribir HTML. Herramientas como Swagger Editor y otras alternativas online te permiten:

Ver la lista de endpoints en un menú lateral.
Desplegar cada operación para revisar parámetros y respuestas.
Probar llamadas directamente desde el navegador si configuras el servidor correctamente.

El flujo básico sería así:

Renderizando diagrama…

En otras palabras: una vez que tienes el contrato en OpenAPI, ese archivo se convierte en la fuente de verdad que alimenta docs, tests, mocks y clientes. No necesitas reescribir la misma información en muchos sitios distintos.

Además de los editores genéricos, puedes trabajar directamente sobre tu contrato dentro de Capydox: el workspace incluye un editor OpenAPI que actúa como visualizador tipo Swagger Editor y te permite importar un swagger existente, generar documentación enriquecida y, si ya trabajas con colecciones de tests, convertir colecciones en contratos OpenAPI o al revés (crear colecciones a partir de tu swagger). Así mantienes en el mismo sitio contrato, documentación y evidencia de pruebas.

Por qué tiene sentido escribir OpenAPI incluso en proyectos pequeños

Puede parecer que OpenAPI es algo “pesado” reservado para grandes empresas o APIs públicas con miles de usuarios. En la práctica, los proyectos pequeños se benefician todavía más:

Evitas olvidar detalles: al tener que definir parámetros, modelos y respuestas, piensas mejor el diseño de tu API.
Facilitas el trabajo futuro: cuando vuelves meses después al proyecto, el contrato te recuerda cómo se comporta cada endpoint sin tener que leer todo el código.
Abres la puerta a automatización: aunque al principio solo uses el spec para generar docs, más adelante podrás añadir validaciones en CI, mocks, SDKs, etc.

Si trabajas em um equipo, OpenAPI se convierte em o linguagem compartilhado entre backend, frontend, QA y cualquier integrador externo. Todos hablan de lo mismo: el contrato.

Siguientes pasos y cómo encaja Capydox

Con tu primer openapi.yaml funcionando, el siguiente nivel es integrar ese contrato en tu flujo de trabajo habitual:

Versionar el archivo junto al código en Git.
Revisar cambios en el contrato a través de pull requests, igual que el código.
Añadir checks automáticos para validar que el spec es consistente antes de hacer deploy.

A partir de ahí puedes conectar herramientas alrededor de ese contrato. Capydox, por ejemplo, puede usar tu OpenAPI como materia prima para generar documentación más rica, enlazarla con evidencias de pruebas y ayudarte a mantener la doc alineada con lo que realmente se está ejecutando en tus entornos.

La idea de fondo es sencilla: cuanto antes conviertas tu API en un contrato explícito, más fácil será documentarla, probarla y evolucionarla sin sorpresas.

OpenAPI para principiantes: escribe tu primer contrato en 20 minutos