¿Cómo puedo documentar una API existente con OpenAPI? #
Documentar una interfaz de programación de aplicaciones (API) existente puede ser sin duda una tarea desafiante, sobre todo cuando se necesita que la documentación sea a la vez completa y legible. OpenAPI, conocida anteriormente como Swagger Specification, ofrece un marco potente para describir, producir, consumir y visualizar servicios web RESTful. En este artículo exploraremos cómo puedes documentar una API existente con la especificación OpenAPI.
Comprender OpenAPI #
Antes de empezar a documentar tu API, es fundamental entender qué es OpenAPI. OpenAPI es una especificación para definir y documentar API. Permite que tanto personas como equipos informáticos comprendan las capacidades de un servicio sin acceder al código fuente ni inspeccionar el tráfico de red.
La especificación OpenAPI puede definir:
- Los endpoints (rutas) de la API.
- Las operaciones (métodos HTTP como GET, POST, PUT, DELETE) de cada endpoint.
- Los parámetros de entrada y el formato de salida de cada operación.
- Los métodos de autenticación.
- La información de contacto, la licencia, los términos de uso y otros metadatos.
Para obtener más detalles sobre OpenAPI, puedes consultar el sitio web oficial de la OpenAPI Initiative.
Pasos para documentar una API existente con OpenAPI #
1. Evalúa tu API #
Empieza evaluando la API existente. Identifica todos los endpoints junto con sus métodos, parámetros, cuerpos de solicitud y cuerpos de respuesta. Este paso puede requerir que uses herramientas como Postman, o que examines el código fuente si tienes acceso a él.
2. Elige la versión de OpenAPI #
A continuación, elige la versión de OpenAPI que quieres usar. En 2026, OpenAPI 3.2.0 es la versión más reciente, aunque las líneas 3.0.x y 3.1.x, ampliamente compatibles, siguen siendo opciones perfectamente válidas. Consulta el repositorio de GitHub de las especificaciones de OpenAPI para conocer la versión publicada más reciente.
openapi: 3.0.3
3. Inicializa el documento OpenAPI #
Empieza configurando la estructura básica de tu documento OpenAPI. Esto incluye la versión, el título, la descripción y la URL del servidor.
openapi: 3.0.3
info:
title: Your API Title
description: A brief description of your API
version: 1.0.0
servers:
- url: https://api.yourdomain.com/v1
description: Main (production) server
4. Define las rutas #
Define las rutas (endpoints) y las operaciones (métodos HTTP) que admite cada endpoint. Cada ruta contendrá información sobre los métodos HTTP (GET, POST, etc.) y sobre los parámetros de solicitud y las respuestas esperadas.
paths:
/users:
get:
summary: Retrieve a list of users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
5. Describe los parámetros y los cuerpos de solicitud #
Documenta los parámetros y los detalles del cuerpo de solicitud de cada operación. Los parámetros pueden ir en la ruta, en la consulta (query), en los encabezados (header) o en las cookies.
paths:
/users:
get:
summary: Retrieve a list of users
parameters:
- name: limit
in: query
description: The number of users to return
required: false
schema:
type: integer
default: 25
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
6. Define los componentes (esquemas) #
Define componentes reutilizables, como esquemas (modelos de datos), respuestas, parámetros, ejemplos y más. Esto ayuda a reducir la redundancia.
components:
schemas:
User:
type: object
properties:
id:
type: integer
description: The user ID
name:
type: string
description: The user's name
email:
type: string
description: The user's email address
7. Añade la autenticación #
Si tu API requiere autenticación, debes describir los métodos de autenticación que admite. OpenAPI admite varios mecanismos de autenticación, entre ellos la autenticación HTTP, las claves de API, OAuth2 y OpenID Connect.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
8. Añade documentación y ejemplos de la API #
Proporcionar ejemplos de solicitudes y respuestas puede ser muy útil para los desarrolladores. Puedes añadir ejemplos directamente en cada operación o dentro de la sección components para reutilizarlos.
paths:
/users/{id}:
get:
summary: Retrieve a specific user
parameters:
- name: id
in: path
required: true
description: The user ID
schema:
type: integer
responses:
'200':
description: A user object
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
sample:
summary: Example user
value: { "id": 1, "name": "John Doe", "email": "john.doe@example.com" }
9. Pruebas e iteración #
Una vez documentada la API, es importante probar su documentación para asegurar que sea precisa. Herramientas como Swagger Editor, Swagger UI y Postman son muy útiles durante esta fase.
10. Genera la documentación #
Por último, puedes generar documentación interactiva de la API con herramientas como Swagger UI o Redoc. Estas herramientas permiten crear una página web que los desarrolladores pueden usar para interactuar con tu API.
Ejemplo de documentación OpenAPI #
A continuación se muestra un ejemplo sencillo de un documento OpenAPI para una API de usuarios:
openapi: 3.0.3
info:
title: User API
description: API for managing users
version: 1.0.0
servers:
- url: https://api.example.com/v1
description: Production server
paths:
/users:
get:
summary: Retrieve a list of users
parameters:
- name: limit
in: query
description: The number of users to return
required: false
schema:
type: integer
default: 25
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
/users/{id}:
get:
summary: Retrieve a specific user
parameters:
- name: id
in: path
required: true
description: The user ID
schema:
type: integer
responses:
'200':
description: A user object
content:
application/json:
schema:
$ref: '#/components/schemas/User'
examples:
sample:
summary: Example user
value: { "id": 1, "name": "John Doe", "email": "john.doe@example.com" }
components:
schemas:
User:
type: object
properties:
id:
type: integer
description: The user ID
name:
type: string
description: The user's name
email:
type: string
description: The user's email address
Conclusión #
Documentar una API existente con OpenAPI puede parecer abrumador al principio, pero si sigues un enfoque estructurado, podrás crear una documentación clara y completa que beneficie tanto a tu equipo de desarrollo como a los consumidores de tu API. Con herramientas como Swagger Editor y Swagger UI, el proceso se vuelve aún más ágil e interactivo. Recuerda que una buena documentación es un proceso continuo y puede necesitar actualizaciones a medida que la API evoluciona.
Para profundizar y conocer más herramientas, estos recursos pueden resultarte útiles:
Última actualización: 12 de agosto de 2026.