¿Qué herramientas pueden generar automáticamente un documento OpenAPI a partir del código existente?

¿Qué herramientas pueden generar automáticamente un documento OpenAPI a partir del código existente? #

No todas las API nacen con un documento OpenAPI diseñado de antemano (design-first). Muchos equipos tienen bases de código ya existentes —API REST creadas con Express, Spring Boot, FastAPI, Rails u otros frameworks— y necesitan producir un documento OpenAPI para mejorar la documentación, habilitar la generación de código para los consumidores o aplicar herramientas de gobernanza. Afortunadamente, existe un ecosistema maduro de herramientas que generan OpenAPI a partir del código para todos los principales lenguajes y frameworks, desde generadores basados en anotaciones hasta herramientas de introspección en tiempo de ejecución.

Dos enfoques: basado en anotaciones frente a introspección en tiempo de ejecución #

Las herramientas de este ámbito siguen uno de dos enfoques generales:

La generación basada en anotaciones exige que los desarrolladores anoten su código (controladores, modelos, manejadores de rutas) con metadatos que la herramienta lee para producir un documento OpenAPI. Las anotaciones conviven con el código, de modo que el documento se mantiene sincronizado a medida que el código se actualiza. La mayoría de los frameworks de Java y .NET siguen este patrón.

La introspección en tiempo de ejecución funciona examinando la tabla de rutas, el middleware y la información de tipos de la aplicación en ejecución para inferir la estructura de la API. Requiere menos anotación manual, pero puede producir un documento menos completo o preciso, especialmente en los esquemas de solicitud y respuesta.

Python: FastAPI #

FastAPI es posiblemente el mejor ejemplo de generación automática de OpenAPI en cualquier lenguaje. Como FastAPI utiliza las anotaciones de tipo de Python y los modelos de Pydantic para definir los esquemas de solicitud y respuesta, puede generar un documento OpenAPI 3.1 completo y preciso sin anotaciones adicionales:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: str
    email: str
    name: str | None = None

@app.get("/users/{user_id}", response_model=User)
def get_user(user_id: str):
    ...

FastAPI sirve automáticamente el documento OpenAPI en /openapi.json e incorpora Swagger UI en /docs y Redoc en /redoc. No se necesitan herramientas ni pasos adicionales.

Python: Flask y Django #

Para las aplicaciones de Flask, flask-openapi3 y Flasgger permiten generar OpenAPI mediante anotaciones en las docstrings o mediante la integración con esquemas de Marshmallow o Pydantic.

Para Django REST Framework, dentro de Django, drf-spectacular es la herramienta más completa. Analiza los serializadores, las vistas y los enrutadores de DRF para producir un documento OpenAPI 3, y admite personalización mediante decoradores @extend_schema.

Java: Springdoc OpenAPI #

springdoc-openapi es el generador de OpenAPI más destacado para aplicaciones de Spring Boot. Al añadir la dependencia, se analizan automáticamente los controladores de Spring MVC y Spring WebFlux y se produce un documento OpenAPI 3:

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.x.x</version>
</dependency>

El documento OpenAPI se sirve en /v3/api-docs y Swagger UI en /swagger-ui.html. Anotaciones como @Operation, @ApiResponse y @Parameter enriquecen el documento generado con descripciones y ejemplos que van más allá de lo que puede inferirse del código.

Springdoc es compatible con Spring Security, la paginación, la carga de archivos y los esquemas polimórficos, lo que lo hace apto para producción en aplicaciones Spring complejas.

Java: Quarkus y Micronaut #

Quarkus incluye generación de OpenAPI integrada mediante la extensión quarkus-smallrye-openapi, que utiliza la especificación MicroProfile OpenAPI. Micronaut ofrece capacidades similares a través de su procesador de anotaciones de OpenAPI, que se ejecuta en tiempo de compilación y produce el documento sin sobrecarga en tiempo de ejecución.

.NET: Swashbuckle y NSwag #

Para las aplicaciones de ASP.NET Core predominan dos herramientas:

Swashbuckle.AspNetCore es la más utilizada. Emplea reflexión y comentarios de documentación XML para generar un documento OpenAPI a partir de las acciones de los controladores y las clases de modelo. A partir de ASP.NET Core 9, Microsoft ha empezado a incluir su propia generación de OpenAPI integrada, pero Swashbuckle sigue estando muy extendido.

NSwag genera tanto el documento OpenAPI como código de cliente en C# o TypeScript a partir de él. Se integra con ASP.NET Core, es compatible con .NET Native AOT y ofrece una API de configuración muy completa.

Node.js: Express y Fastify #

Para Express.js, swagger-jsdoc genera OpenAPI a partir de comentarios JSDoc situados sobre las definiciones de rutas:

/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get a user by ID
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: A user object
 */
app.get('/users/:id', (req, res) => { ... });

Para Fastify, la generación de OpenAPI está integrada en el ecosistema mediante @fastify/swagger, que lee las definiciones de rutas nativas de Fastify basadas en JSON Schema y produce automáticamente un documento OpenAPI.

Para NestJS, el paquete @nestjs/swagger ofrece generación de OpenAPI basada en decoradores con una excelente inferencia de tipos de TypeScript.

Go #

swaggo/swag genera OpenAPI (Swagger 2.0) a partir de los comentarios de Go. Para OpenAPI 3.x, ogen adopta un enfoque que parte del esquema (genera código Go a partir de OpenAPI), mientras que huma genera documentos OpenAPI 3.1 a partir de las definiciones de tipos de Go con anotaciones mínimas.

Ruby on Rails #

rswag integra la documentación OpenAPI con las pruebas de RSpec para las API de Rails. Las pruebas actúan como fuente de referencia del documento OpenAPI, de modo que este siempre refleja el comportamiento probado. grape-swagger ofrece una funcionalidad similar para las API de Grape.

Herramientas de descubrimiento automático #

Para las API heredadas o sin documentar, en las que ni siquiera la generación basada en anotaciones resulta viable, las herramientas que inspeccionan el tráfico pueden generar un documento OpenAPI observando el tráfico real de la API:

  • Optic: registra el tráfico de la API y produce un documento OpenAPI a partir de los pares de solicitud y respuesta observados. También detecta cambios incompatibles al comparar el tráfico con un documento existente.
  • akita (archivado): enfoque similar de inspección de tráfico para generar OpenAPI a partir del tráfico en vivo.

Estas herramientas son especialmente útiles para documentar API existentes cuya base de código no es fácil de instrumentar.

Consideraciones sobre la calidad #

Los documentos OpenAPI generados automáticamente son un punto de partida, no un artefacto terminado. Estas son las carencias habituales que conviene abordar tras la generación:

  • Descripciones ausentes: las herramientas generadoras normalmente no pueden inferir qué hace un endpoint en términos de negocio.
  • Ejemplos incompletos: los esquemas sintetizados rara vez incluyen los ejemplos realistas que hacen útil la documentación.
  • Esquemas demasiado permisivos: los esquemas inferidos pueden usar additionalProperties: true o tipos poco estrictos cuando unas definiciones más estrictas serían más precisas.
  • Respuestas de error ausentes: muchos generadores solo documentan el flujo ideal (happy path).

Tras generar el documento inicial, los equipos deberían planificar una pasada de mejora de la documentación para añadir descripciones, ejemplos y definiciones de respuestas de error.

Conclusión #

Todos los lenguajes y frameworks principales cuentan con herramientas para generar documentos OpenAPI a partir del código existente, desde la generación automática sin configuración de FastAPI hasta los generadores basados en anotaciones para Spring Boot, ASP.NET Core y NestJS. Para los sistemas heredados, herramientas de inspección de tráfico como Optic pueden iniciar la documentación a partir del uso real de la API. Sea cual sea el enfoque elegido, el documento generado debe tratarse como un punto de partida y refinarse con descripciones, ejemplos y respuestas de error adecuadas antes de publicarlo para los consumidores.

Última actualización: 30 de abril de 2026.

Este sitio web no está afiliado a la OpenAPI Initiative.