What tools can automatically generate an OpenAPI document from existing code?

What tools can automatically generate an OpenAPI document from existing code? #

Not every API starts life with a design-first OpenAPI document. Many teams have existing codebases — REST APIs built with Express, Spring Boot, FastAPI, Rails, or other frameworks — and need to produce an OpenAPI document to improve documentation, enable code generation for consumers, or bring governance tooling to bear. Fortunately, a mature ecosystem of code-to-OpenAPI tools exists across every major language and framework, ranging from annotation-driven generators to runtime introspection tools.

Two Approaches: Annotation-Driven vs. Runtime Introspection #

Tools in this space take one of two broad approaches:

Annotation-driven generation requires developers to annotate their code (controllers, models, route handlers) with metadata that the tool reads to produce an OpenAPI document. The annotations live alongside the code, so the document stays in sync as the code is updated. Most Java and .NET frameworks follow this pattern.

Runtime introspection works by examining the running application’s route table, middleware, and type information to infer the API structure. This requires less manual annotation but may produce a less complete or accurate document, especially for request/response schemas.

Python: FastAPI #

FastAPI is arguably the best example of automatic OpenAPI generation in any language. Because FastAPI uses Python type hints and Pydantic models to define request and response schemas, it can generate a complete, accurate OpenAPI 3.1 document with zero additional annotations:

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 automatically serves the OpenAPI document at /openapi.json and provides built-in Swagger UI at /docs and Redoc at /redoc. No extra tools or steps are required.

Python: Flask and Django #

For Flask applications, flask-openapi3 and Flasgger provide OpenAPI generation via docstring annotations or Marshmallow/Pydantic schema integration.

For Django REST Framework, drf-spectacular is the most capable tool. It introspects DRF serializers, views, and routers to produce an OpenAPI 3 document, with support for customization via @extend_schema decorators.

Java: Springdoc OpenAPI #

springdoc-openapi is the leading OpenAPI generator for Spring Boot applications. Adding the dependency automatically scans Spring MVC and Spring WebFlux controllers and produces an OpenAPI 3 document:

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

The OpenAPI document is served at /v3/api-docs and Swagger UI at /swagger-ui.html. Annotations like @Operation, @ApiResponse, and @Parameter enrich the generated document with descriptions and examples beyond what can be inferred from the code.

Springdoc supports Spring Security, pagination, file uploads, and polymorphic schemas, making it production-ready for complex Spring applications.

Java: Quarkus and Micronaut #

Quarkus includes built-in OpenAPI generation via the quarkus-smallrye-openapi extension, which uses the MicroProfile OpenAPI specification. Micronaut provides similar capabilities through its OpenAPI annotation processor, which runs at compile time — producing the document without runtime overhead.

.NET: Swashbuckle and NSwag #

For ASP.NET Core applications, two tools dominate:

Swashbuckle.AspNetCore is the most widely used. It uses reflection and XML documentation comments to generate an OpenAPI document from controller actions and model classes. As of ASP.NET Core 9, Microsoft has begun shipping its own built-in OpenAPI generation, but Swashbuckle remains prevalent.

NSwag generates both the OpenAPI document and C# or TypeScript client code from it. It integrates with ASP.NET Core, supports .NET Native AOT, and provides a rich configuration API.

Node.js: Express and Fastify #

For Express.js, swagger-jsdoc generates OpenAPI from JSDoc comments above route definitions:

/**
 * @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) => { ... });

For Fastify, OpenAPI generation is built into the ecosystem via @fastify/swagger, which reads Fastify’s native JSON Schema route definitions and produces an OpenAPI document automatically.

For NestJS, the @nestjs/swagger package provides decorator-based OpenAPI generation with excellent TypeScript type inference.

Go #

swaggo/swag generates OpenAPI (Swagger 2.0) from Go comments. For OpenAPI 3.x, ogen takes a schema-first approach (generating Go code from OpenAPI), while huma generates OpenAPI 3.1 documents from Go type definitions with minimal annotations.

Ruby on Rails #

rswag integrates OpenAPI documentation with RSpec tests for Rails APIs. Tests act as the source of truth for the OpenAPI document, ensuring the document always reflects tested behavior. grape-swagger provides similar functionality for Grape APIs.

Automatic Discovery Tools #

For legacy or undocumented APIs where even annotation-driven generation is impractical, traffic-sniffing tools can generate an OpenAPI document by observing real API traffic:

  • Optic — records API traffic and produces an OpenAPI document from observed request/response pairs. Also detects breaking changes by comparing traffic against an existing document.
  • akita (archived) — similar traffic-sniffing approach for generating OpenAPI from live traffic.

These tools are especially useful for documenting existing APIs where the codebase is not easily instrumentable.

Quality Considerations #

Auto-generated OpenAPI documents are a starting point, not a finished artifact. Common gaps to address after generation:

  • Missing descriptions — generated tools typically cannot infer what an endpoint does in business terms.
  • Incomplete examples — synthesized schemas rarely include the realistic examples that make documentation useful.
  • Overly permissive schemas — inferred schemas may use additionalProperties: true or loose types where stricter definitions would be more accurate.
  • Missing error responses — many generators only document the happy path.

After generating the initial document, teams should plan a documentation improvement pass to add descriptions, examples, and error response definitions.

Conclusion #

Every major language and framework has tooling to generate OpenAPI documents from existing code, ranging from FastAPI’s zero-configuration automatic generation to annotation-driven generators for Spring Boot, ASP.NET Core, and NestJS. For legacy systems, traffic-sniffing tools like Optic can bootstrap documentation from real-world API usage. Whichever approach is used, the generated document should be treated as a starting point, refined with descriptions, examples, and proper error responses before being published to consumers.

Last updated on April 30, 2026.

This website is not affiliated with the OpenAPI Initiative.