Documentación automática de APIs (Swagger / OpenAPI)

1 Introducción

La documentación es uno de los elementos más importantes en una API REST.

  • Una API mal documentada es difícil de entender y casi imposible de usar por terceros.
  • Una API bien documentada permite que cualquier desarrollador pueda integrarse fácilmente.

👉 El estándar actual para documentar APIs REST es la OpenAPI Specification (OAS), y la herramienta más popular para visualizarla e interactuar con ella es Swagger UI.

2 ¿Qué es OpenAPI?

OpenAPI es una especificación estandarizada para describir APIs REST. Permite definir:

  • Rutas (endpoints).
  • Métodos HTTP (GET, POST, etc.).
  • Parámetros (Path, Query, Header).
  • Estructuras de request y response en JSON.
  • Códigos de estado.
  • Autenticación (API keys, JWT, OAuth2).

👉 Se escribe en YAML o JSON, y sirve como contrato entre el servidor y los clientes.

Ejemplo simple en YAML

openapi: 3.0.0
info:
  title: API de Productos
  version: 1.0.0
paths:
  /productos:
    get:
      summary: Obtener todos los productos
      responses:
        '200':
          description: Lista de productos

3 ¿Qué es Swagger?

Swagger es un ecosistema de herramientas que trabajan con OpenAPI.

  • Swagger UI: genera una interfaz web interactiva para probar la API.
  • Swagger Editor: permite escribir y validar especificaciones OpenAPI.
  • Swagger Codegen: genera clientes y servidores automáticamente a partir de la especificación.

👉 Hoy en día, Swagger UI es lo que los desarrolladores ven más seguido: una página web con la lista de endpoints donde pueden probar la API en tiempo real.

4 Beneficios de usar Swagger / OpenAPI

  • Documentación automática: se genera desde el código o la especificación.
  • Interactividad: los desarrolladores pueden ejecutar peticiones directamente desde la doc.
  • Estandarización: todas las APIs siguen la misma estructura.
  • Generación de SDKs: se pueden generar clientes en Java, Python, C#, etc., automáticamente.
  • Mejora la comunicación: es un contrato claro entre backend y frontend.

5 Ejemplo de documentación en Swagger UI

Supongamos que tenemos una API con este endpoint:

GET /productos

En Swagger UI se vería así:

  • Método: GET
  • Ruta: /productos
  • Descripción: Devuelve todos los productos.
  • Respuesta 200:
[
  { "id": 1, "nombre": "Notebook", "precio": 1500 },
  { "id": 2, "nombre": "Tablet", "precio": 900 }
]

👉 El desarrollador puede presionar Try it out, ejecutar la petición y ver la respuesta directamente.

6 Ejemplo de especificación OpenAPI completa (YAML)

openapi: 3.0.0
info:
  title: API de Usuarios
  version: 1.0.0
paths:
  /usuarios:
    get:
      summary: Listar usuarios
      responses:
        '200':
          description: Lista de usuarios
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Usuario'
    post:
      summary: Crear un nuevo usuario
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Usuario'
      responses:
        '201':
          description: Usuario creado
  /usuarios/{id}:
    get:
      summary: Obtener usuario por ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Usuario encontrado
components:
  schemas:
    Usuario:
      type: object
      properties:
        id:
          type: integer
        nombre:
          type: string
        email:
          type: string

👉 Esto genera automáticamente una documentación completa con ejemplos de peticiones y respuestas.

7 Swagger en frameworks populares

FastAPI (Python)

  • Swagger UI y ReDoc se generan automáticamente en: http://localhost:8000/docs (Swagger) y http://localhost:8000/redoc (ReDoc).

Spring Boot (Java)

  • Usando la librería springdoc-openapi: la doc se genera en http://localhost:8080/swagger-ui.html.

Express (Node.js)

8 Ejemplo práctico con FastAPI

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Producto(BaseModel):
    id: int
    nombre: str
    precio: float

@app.get("/productos", response_model=list[Producto])
def listar_productos():
    return [
        {"id": 1, "nombre": "Notebook", "precio": 1500},
        {"id": 2, "nombre": "Tablet", "precio": 900}
    ]

👉 Al ejecutar la app, FastAPI genera automáticamente documentación en Swagger UI (/docs) y en ReDoc (/redoc).

9 Buenas prácticas en la documentación automática

  • Definir ejemplos de request y response: ayuda a los desarrolladores a entender cómo interactuar.
  • Incluir descripciones claras para cada endpoint y campo.
  • Documentar errores posibles, no solo los casos de éxito.
  • Actualizar la especificación cada vez que cambie la API.
  • Versionar la documentación: /api/v1/docs, /api/v2/docs.

10 Conclusión del capítulo

OpenAPI es el estándar actual para describir APIs REST. Swagger es el ecosistema de herramientas más usado para generar documentación interactiva.

Una API documentada con Swagger permite que cualquier desarrollador la entienda y la pruebe fácilmente.

La documentación automática convierte a la API en algo profesional, transparente y usable.

👉 En resumen: si tu API no tiene documentación automática, está incompleta.

Retornar