How to generate OpenAPI spec from code: A practical guide

A pull request lands on Friday afternoon. It adds two endpoints, changes a response body, and updates auth rules on an existing route. Deployment passes. By the next week, another team is building against the old contract, QA is testing the previous response shape, and the fastest way to answer a basic API question is still opening the route handler.

That failure pattern is why teams look for how to generate OpenAPI spec from code. Manual documentation usually breaks under normal release pressure, especially once multiple services, owners, and consumers are involved.

The actual goal is not generating a spec once. The goal is keeping the spec current every time code changes, then validating it in the same pipeline that runs tests and ships builds. Teams that treat OpenAPI as a build artifact get a reference that stays aligned with production behavior. Teams that treat it as a side document end up arguing about whether the code or the docs reflect reality. For a practical example of auto-generating API documentation from code and keeping it tied to development workflows, that pattern is worth studying before choosing tools.

I have seen the trade-off play out across backend stacks. Handwritten specs give strong control early on, but they drift unless someone owns them aggressively. Code-first generation is less elegant in theory and far more reliable in day-to-day delivery. It works especially well when spec generation, linting, and diff checks run in CI/CD, and when the repository treats documentation changes the same way it treats test failures.

DocuWriter.ai fits that workflow in a factual, practical way. It supports Swagger and OpenAPI generation, README creation, UML diagrams, refactoring support, and an Autopilot AI Agent that watches repositories in GitHub, GitLab, Bitbucket, and Azure DevOps for code changes.

The endless pain of stale API documentation

The most common failure pattern is boring. A team writes docs once, promises to keep them updated, then stops doing it when deadlines get tight. Nobody makes that decision explicitly. It just happens one rushed release at a time.

The damage shows up in small ways first. A frontend engineer copies an outdated request body. An integration partner assumes a field is required because the docs still say so. A platform team changes auth middleware, but the public reference never reflects it. Suddenly the argument isn’t about implementation. It’s about whose version of reality matters more, the docs or the code.

Where it hurts in practice

Stale API docs slow down work in places that managers and staff engineers both care about:

• Onboarding gets messy: New hires can’t tell which endpoints are current, so they reverse engineer handlers and tests.
• Cross-team integration gets risky: Consumer teams build against contracts that no longer match production behavior.
• Audit prep becomes reactive: When someone asks for current API references, teams scramble to reconstruct them from source.
• Ownership handovers break down: Consulting teams, internal platform groups, and acquired engineering orgs often inherit codebases with partial or missing API documentation.

A bigger problem appears in mixed environments. Plenty of guides assume you can cleanly add annotations everywhere, but real codebases don’t look like that. In heterogeneous or legacy services, annotations may be incomplete, inconsistent, or impossible to add broadly, and mainstream guidance often doesn’t address that gap for organizations that need cross-repo, cross-language, always-current specs from real codebases, as noted by Stainless on creating OpenAPI from existing code.

Why manual specs decay

Manual specs decay because they live in a different workflow than the code. Engineers change handlers, serializers, validation rules, and security middleware in one pull request. The OpenAPI file sits somewhere else, owned by habit instead of enforcement.

That’s why the better model is to treat the spec as an artifact of delivery. Generate it from implementation where possible. Validate it in CI. Review diffs like code. Publish automatically.

For teams trying to escape stale references, a useful starting point is this guide on auto generated API documentation workflows.

Choosing your strategy code-first vs design-first

There are two workable ways to manage an API contract. One starts with the specification. The other starts with the implementation and emits the specification from code.

The OpenAPI Specification itself supports machine-readable API descriptions used by documentation generators, and OpenAPI 3.1.0 was published in 2021. In practice, code-first generation works by attaching metadata to source code or framework routes and extracting an OpenAPI document from there, which is exactly the kind of tool-driven workflow the spec was designed to support according to the OpenAPI Specification.

Design-first

Design-first means the OpenAPI document is the blueprint. Teams agree on paths, schemas, auth, and responses before implementation begins.

Pros

• Clear contract early: Frontend, backend, QA, and partner teams can align before code lands.
• Good for public APIs: Product and platform teams can review the contract as a deliverable.
• Strong governance: Reviewers can enforce naming, consistency, and reuse before implementation details spread.

Cons

• Higher upfront friction: Teams have to stop and model everything before building.
• Easy to drift later: If code changes faster than the spec review process, the contract goes stale anyway.
• Not ideal for brownfield systems: Existing services rarely fit neatly into a clean, spec-first redesign.

Code-first

Code-first means the application is the source of truth. Tooling extracts the contract from routes, types, annotations, and runtime metadata.

Pros

• Stays close to reality: The generated contract reflects what the app exposes.
• Fits existing systems better: You can start from a live codebase instead of rewriting process around a spec.
• Faster adoption: Teams can add documentation generation incrementally.

Cons

• Generated output can be rough: Without good annotations and conventions, the spec may be technically valid but hard to use.
• Edge cases need help: Polymorphism, custom serializers, and security details often need explicit metadata.
• Tooling varies by stack: Some frameworks make this easy. Others need more assembly.

If you’re building a brand new platform API with heavy stakeholder review, design-first can be the right constraint. If you’re trying to fix documentation in a living system, code-first is usually the path that gets adopted.

Generating specs from popular languages and frameworks

Development teams don’t need a philosophical answer. They need a repeatable workflow for their stack.

A mature example of this pattern appears in APIFlask. It collects information from configuration, routes, and decorators, then generates the OpenAPI document automatically. It also supports exporting the spec with a flask spec command, which shows how code-first generation has become part of normal development and CI workflows in frameworks that embrace it, as documented in APIFlask OpenAPI generation.

Python with APIFlask

APIFlask is one of the clearest examples of code-first documentation because the framework is built around generating the spec from the app definition.

from apiflask import APIFlask

app = APIFlask(__name__)

@app.get('/hello')
def hello():
    return {'message': 'hello'}

Generate the spec:

flask spec --output openapi.json --format json

Why this works well:

• Routes are first-class inputs: The framework already knows the path and method.
• Metadata stays nearby: Decorators and configuration supply descriptions and schema details.
• CI is straightforward: The same command can run locally and in build pipelines.

Java with Spring

In Java shops, Spring is a common place to generate OpenAPI from controller metadata and model definitions. The exact library choice varies, but the pattern is consistent: annotate routes and models, start the app, then export the emitted contract.

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable String id) {
        return new User(id, "Ada");
    }
}

A practical workflow is usually:

1. Add OpenAPI support to the Spring application.
2. Expose the generated contract endpoint at runtime.
3. Download or copy that output into openapi.json during CI.

For teams scaling this across multiple Java services, having strong internal conventions matters as much as the framework choice. If you’re staffing up around that ecosystem, this guide to hiring java developers is useful context because the quality of generated specs often depends on how consistently engineers model controllers, DTOs, and validation.

For a deeper Java-specific walkthrough, see this guide on Java API documentation from code.

Node.js with Express

Express gives flexibility, which is both useful and dangerous. Since the framework itself doesn’t impose a schema model, teams often rely on JSDoc, route metadata, or wrapper libraries.

const express = require('express');
const app = express();

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(3000);

The usual generation pattern looks like this:

• Add route metadata: JSDoc comments or library-specific schema declarations
• Run the app or a build script: Let the tooling collect route definitions
• Emit **openapi.json**: Save the generated output as a build artifact

Express can work well, but only if the team agrees on one convention. Mixed styles inside the same codebase usually produce incomplete output.

.NET with ASP.NET Core

ASP.NET Core has become increasingly capable at deriving contract information from endpoint definitions and related metadata. A common setup is to register OpenAPI services, run the app, and expose the generated document.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapGet("/ping", () => new { message = "pong" });

app.Run();

Typical workflow:

• Start the application locally or in CI
• Retrieve the generated OpenAPI document from the configured endpoint
• Store it as openapi.json or publish it directly

This approach is especially effective when teams already write XML comments, response metadata, and typed request models consistently.

Go with Gin

Go teams often favor explicit handlers and structs, which can map cleanly into OpenAPI generation when paired with comments or schema tags.

r := gin.Default()

r.GET("/books/:id", func(c *gin.Context) {
    c.JSON(200, gin.H{"id": c.Param("id"), "title": "Distributed Systems"})
})

r.Run()

The practical pattern is familiar by now:

• Annotate handlers or models in the style your tooling expects
• Run the generation command as part of build or CI
• Treat the resulting spec like any other artifact

Across all of these stacks, the same lesson holds. The first spec generation is easy. The useful part is making sure the team can regenerate it every time code changes.

Validating and testing your generated spec

A generated spec isn’t automatically trustworthy. It can be structurally valid and still be misleading, incomplete, or awkward for consumers.

Swagger’s guidance describes a practical path: add OpenAPI dependencies, generate the contract from the running application, then validate it before publishing. That matters because code-first tools don’t infer everything correctly, especially with complex schemas and security definitions, as explained in Swagger’s guide to documenting APIs with Swagger.

Lint the file

Linting catches avoidable contract mistakes before they become published docs or broken SDK inputs. Teams often use Spectral or similar linters to enforce naming, descriptions, examples, and consistency rules.

A minimal pattern looks like this:

spectral lint openapi.json

Good lint rules usually focus on things humans skip when they’re moving fast:

• Missing descriptions: Operations and schemas without usable context
• Inconsistent naming: Paths, tags, and components that drift across services
• Schema quality issues: Ambiguous types, poor examples, or incomplete response definitions

Test against the running API

Contract validation gets more useful when you compare the spec to a real service. That can mean contract testing tools that execute requests from the OpenAPI description and verify that responses match the documented shape.

If your team is already tightening payload validation, this write-up on expert JSON object data validation is relevant because a lot of OpenAPI quality problems show up first as weak or inconsistent schema expectations in actual request and response bodies.

Review the rendered output

Machine checks don’t tell you whether the documentation is readable. A human still needs to open the rendered result in a UI and inspect it the way an API consumer would.

Look for these issues:

• Descriptions that say nothing: “Success response” is valid, but useless.
• Examples that don’t match actual payloads: Common when custom serializers reshape output.
• Security details that are technically present but unclear: Consumers need to know how to authenticate, not just that auth exists.

Teams often realize they need more than just generation. They need curation, review, and testing around the generated artifact. If your engineers are building that practice out, this primer on API testing workflows for engineering teams fits naturally beside spec validation.

Automating spec generation in your CI/CD pipeline

A team merges a harmless-looking serializer change on Friday. By Monday, one client is failing because a field changed shape, the docs still show the old response, and nobody noticed in review because the OpenAPI file was generated manually two weeks ago. That failure pattern is common. The fix is also straightforward. Generate the spec inside CI, treat it like any other build artifact, and fail the pipeline when the contract drifts.

A good pipeline makes API documentation continuous. Every pull request should produce a fresh spec from the current code, run validation, and show reviewers what changed in the contract before merge. That keeps the OpenAPI document tied to delivery instead of relying on someone to remember an export command.

What the pipeline should do

Typically, the CI job needs four checks on every pull request:

1. Build the service
2. Generate the OpenAPI document
3. Lint and validate the result
4. Publish the diff for review or publish the artifact on merge

That setup makes contract changes visible at the same point engineers already review code, tests, and migrations.

Here’s a generic example:

steps:
  - name: build
    run: ./build.sh

  - name: generate-openapi
    run: ./scripts/export-openapi.sh > openapi.json

  - name: lint-openapi
    run: spectral lint openapi.json

  - name: check-diff
    run: git diff, openapi.json

In practice, I usually add one more step. Store the generated file as a pipeline artifact so reviewers, SDK generation jobs, and doc publishing jobs all consume the same output. That removes a surprising amount of drift between environments.

What usually goes wrong

Generation itself is rarely the hard part. Teams usually struggle with process gaps around it.

• One-time exports: openapi.json gets committed once, then gradually falls out of sync with the handlers.
• No diff review: Breaking contract changes ship because nobody saw that a required field disappeared or a status code changed.
• Spec generation depends on local machines: A developer’s plugin, environment variable, or framework version changes the output.
• Docs are generated but never published: The file exists in CI logs, but consumers never see an updated reference.

A useful team rule is simple: if a pull request changes API behavior, it should also produce a spec diff. Reviewers should be able to inspect the contract impact without running the service locally.

Manual scripting works, especially for one service. It gets harder across ten repositories with different frameworks and release patterns. At that point, centralizing generation, review, and publishing usually saves time. Some teams handle that with shared CI templates. Others use documentation automation that watches repository changes and opens updates automatically. DocuWriter.ai is one example of that approach. It can monitor code changes across GitHub, GitLab, Bitbucket, and Azure DevOps, then generate documentation updates, including OpenAPI and Swagger output, as part of a broader docs workflow.

If you are standardizing this across multiple services, this guide to CI/CD pipeline documentation practices is a useful reference.

Versioning and best practices for maintainable specs

The difference between a usable generated spec and a forgettable one is usually maintainability, not syntax. Teams get the file generated, then stop short of making it clear, stable, and reviewable.

Treat versioning as part of the contract

If your API version lives in the URL, the generated spec should make that obvious and consistent across paths. If versioning is header-based or negotiated differently, document that behavior explicitly in operation metadata and auth descriptions.

What matters most is consistency. Consumers should be able to answer two questions quickly:

• Which version am I integrating with?
• What changed between versions that affects my client?

Don’t let versioning live only in tribal knowledge or release notes.

Enrich the generated output

Raw generated specs are often thin. They may include paths, methods, and schemas while leaving out the details that make the reference useful.

Improve the contract with metadata that generators won’t infer cleanly on their own:

• Operation descriptions: Explain intent, not just route shape
• Examples: Show realistic request and response bodies
• Error responses: Document common failure modes clearly
• Security details: Spell out what clients must send and where
• Schema annotations: Clarify nullable fields, enums, and custom formats

Engineering discipline matters here. The implementation may already be correct, but if your annotations are sparse, your docs will still feel incomplete.

Keep the spec in the same pull request

A maintainable process has one hard rule. Documentation changes ship with code changes. Not later. Not after release. Not when someone remembers.

That applies whether the spec is committed directly, published from CI, or generated by a repository automation flow. Teams that separate code review from contract review usually create drift again, just with better tooling.

From code to continuous documentation with AI

Most guides stop after showing how to produce openapi.json once. That’s the easy part. The hard part is keeping the contract current when repositories keep moving, teams keep changing, and services keep multiplying.

A practical documentation system does three things well. It extracts the contract from real code. It validates that contract continuously. It updates documentation as part of the normal delivery path instead of as cleanup work after the release.

That shift changes a lot of downstream work. Onboarding gets easier because engineers trust the reference. Integrations get smoother because consumers aren’t guessing at payloads. Audit prep gets less chaotic because current API documentation already exists. Codebase handovers improve because the docs reflect the software as it stands, not as it stood six months ago.

If you’re moving toward that model, AI is most useful when it removes maintenance effort, not when it creates another review burden. Repository-aware automation can watch code changes, propose updated docs, and keep OpenAPI references from drifting out of sync with implementation. For teams exploring that broader workflow, this article on AI for engineering documentation is a solid companion.

If you want a practical way to keep API docs synced with code after the initial setup, try DocuWriter.ai. It generates OpenAPI/Swagger documentation, code documentation, READMEs, UML diagrams, and refactoring suggestions from source code, and its Autopilot AI Agent can watch repositories on GitHub, GitLab, Bitbucket, and Azure DevOps to suggest or auto-apply documentation updates as the code changes.