What the Generator Can't Write
The tool generates the reference. The judgment, the examples, and the spec itself are still yours.
“Gets user.” “Updates record.” “Deletes thing.”
Those are developer notes, written as reminders inside code, and they land in published API reference documentation unchanged. The generator did its job. Every endpoint is covered, every parameter appears, every response code is listed. The reader gets a complete map with nothing written on it.
Maurice Alvarado, a technical writer at SoftServe, ran into this on a project built with LoopBack 4, a framework that assembles the OpenAPI file from specifications developers write inside their code. He wrote about assuming the framework had ended his usefulness on that team. It hadn’t. Descriptions had gone into whatever field was closest to hand, and by the time he joined, the team considered the reference done and “asked me to review it just in case.”
The reflex when someone mentions auto-generating API documentation is the same anxiety Alvarado describes: if the tool generates the docs, what’s left for us to do? Context, working examples, the mistakes people make, and which endpoints a user actually needs for the task in front of them. Generated reference is thorough and mechanical. It covers the full surface of the API and explains none of it. That’s the writing work.
Understanding how the generation works makes you better at filling the gaps.
What the OpenAPI Specification Is
The OpenAPI Specification (OAS) is a standardized format for describing REST APIs in a machine-readable file, either YAML or JSON. The file describes the API’s endpoints, parameters, request body structures, and response formats in a consistent schema.
The Swagger toolchain is now a set of tools built around OpenAPI files: Swagger UI (a browser-based interface for exploring and testing an API), Swagger Editor (a browser-based editor for writing OpenAPI specs), and Swagger Codegen (for generating client libraries and server stubs from specs). Codegen has largely been overtaken by OpenAPI Generator, the community-maintained fork that ships more than fifty client generators. Both still exist, and you’ll hear either name depending on the team.
The specification was originally called Swagger, until SmartBear donated it to the OpenAPI Initiative in 2015. It was renamed OpenAPI in January 2016, and SmartBear kept the Swagger name for the tooling. That split is the whole source of the confusion.
When developers say “we have Swagger docs,” they usually mean their API is described in an OpenAPI file, and they’re using Swagger UI to render it. The documentation you see at a URL ending in /api-docs or /swagger-ui is typically auto-generated from an OpenAPI spec.
Swagger UI isn’t the only renderer. Redoc is the other one you may encounter. It produces a three-panel layout: navigation on the left, the reference in the middle, request and response examples on the right. It reads more like documentation and less like a test console, and it rewards a richly written spec, because Markdown in your description fields renders properly instead of collapsing into a single line. Both tools read the same file, so the choice between them is a presentation decision rather than a content one.
Reading an OpenAPI File
A basic understanding of YAML is sufficient to read most OpenAPI files. YAML uses indentation to indicate structure (like Python), colons to separate keys from values, and hyphens for list items.
An OpenAPI endpoint definition looks like this:
/users/{id}:
get:
summary: Retrieve a user by ID
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: User found
'404':
description: User not foundThe structure matches what you learned in the last article: endpoint path, HTTP method, parameters with type and whether required, and responses by status code. Reading the spec gives you a complete picture of what the API does, often more complete than what the prose documentation says.
What the Generator Doesn’t Write
The technical writer’s job in an OAS workflow is usually to improve the content of the spec itself: expanding summaries, writing parameter descriptions that explain valid values and edge cases, adding examples that run. It is not maintaining a parallel prose document. That means editing YAML files in a repository, submitting pull requests, working inside the engineering workflow rather than alongside it.
The judgment involved is mostly about placement. At one company I worked for, error documentation ran to 17 separate microservice files, each maintained independently, each repeating its own different version of 400 and 401 descriptions. Restructuring it into three layers (errors shared across all services documented once, service-level errors documented at the service, endpoint-specific errors at the endpoint) cut total volume by roughly 70%. Almost none of that was writing new prose. It was deciding what belonged where, then deleting the duplicates once the shared errors had a home. An OpenAPI spec needs the same decisions in a different file format.
In a mature workflow, the reference lives in the spec and engineers maintain it as part of writing code. Conceptual documentation lives separately and is written by technical writers: getting started guides, authentication setup, use-case walkthroughs, tutorials. GitHub and Stripe both work this way, publishing their OpenAPI descriptions on GitHub while maintaining hand-written guides alongside the generated reference.
The third job is the one nobody assigns: auditing the spec for documentation quality. For each operation, ask:
Does the summary say what the operation does, or does it restate the endpoint name?
Does every parameter description give valid values and edge cases, or only a type?
Is there an example, and does it run?
Are error responses explained, or listed as bare status codes with no description?
Do the descriptions use the same terms as the conceptual docs, or has a second vocabulary crept in?
That audit is where a writer adds the most in a generated workflow, and it’s the part most likely to go undone, because nobody’s job description assigns it.
Spec-First vs. Code-First
Spec-first and code-first are the two ways teams get to an OpenAPI file. In a spec-first approach, the OpenAPI spec is written before any code: the spec defines the API, then engineers implement it. This is where technical writers can contribute earliest, because the documentation is being designed before anything is built.
In a code-first approach, engineers write the code and the spec is generated from annotations in the codebase. Both produce an OpenAPI spec, but the spec-first approach gives the documentation team a seat at the design table.
If your organization is starting a new API project and hasn’t settled the methodology, push for the spec-first case. Know going in that most engineering teams have already picked a side, and that the stated answer is usually better than the real one. Postman’s 2025 State of the API report surveyed more than 5,700 developers and found 82% of organizations claiming API-first practices at some level, with a quarter describing themselves as fully API-first. “Some level” is carrying most of the weight in that sentence. Winning the argument usually means showing a concrete cost of the current approach: a specific incident where a late or inconsistent spec broke an integration or shipped wrong documentation.
Keeping the Spec Honest
Moving the reference into a spec doesn’t make it true. It relocates drift.
In a code-first workflow, the generated spec tracks the shape of the code, because it’s read out of the code. The prose tracks nothing. A description written the week an endpoint shipped sits there unchanged while the endpoint’s behavior moves underneath it. The result is a spec that’s structurally correct and semantically stale, which is worse than a stale prose page: the structural accuracy is what convinces a reader to trust the rest.
Spec-first drifts the other direction. The spec is the contract, and nothing stops an engineer from implementing something slightly different unless something checks.
Two things close the gap, and both belong in CI rather than on somebody’s calendar.
Lint the spec. Spectral, Stoplight’s open-source linter, checks an OpenAPI file against a ruleset you write. Three rulesets come built in, covering OpenAPI, AsyncAPI, and Arazzo, and you extend those with rules of your own. Run spectral lint api.yaml locally, then wire the same command into pull request checks so a spec that breaks the rules fails the build.
This is the most useful item on the list for a technical writer, because a Spectral ruleset is a style guide that executes. Every operation has a description. Every parameter description clears a minimum length. Every response carries an example. Rules you would otherwise enforce by asking nicely in code review, over and over.
Know what it can’t do. A linter confirms a description exists. It has no opinion about whether the description is any good. “Gets user” satisfies a required-description rule, and “Gets user” is where this article started. Linting the spec buys you a floor, not a ceiling, and prose quality is still a human read.
Test the API against the spec. Contract testing checks that the running API does what the spec claims. Prism mocks a server from your spec, so client teams can build against the contract before the API exists. Dredd and Schemathesis run the other direction, exercising the real API and reporting where it diverges from its own description.
Neither of those is yours to build. Learn the names anyway. When you ask what validates the spec against the actual API and the answer is nothing, you have found the reason the reference is wrong.
OpenAPI describes REST APIs, and sooner or later someone hands you something that isn’t one. GraphQL, gRPC, and event-driven systems each have their own description format, their own generator, and the same gap between what the generator produces and what a developer needs, which is enough material for its own article.
Further Reading
Tom Johnson’s API documentation course, Chapter 4: OpenAPI spec and generated reference docs — a full chapter on the spec, the tools that render it, and spec-first development, with hands-on tutorials. The deepest free treatment of this topic anywhere.
OpenAPI Initiative, official specification at spec.openapis.org — the primary source, maintained by the Linux Foundation, with the latest version linked from the homepage.
Swagger’s documentation at swagger.io/docs — actively maintained, practical guidance on Swagger UI, Editor, and Codegen specifically.
Spectral at stoplight.io/open-source/spectral — the linter, its built-in rulesets, and how to write your own. Stoplight also publishes ready-made style guides you can export as Spectral files.
AsyncAPI at asyncapi.com — the specification for event-driven APIs, with its own docs, generators, and migration guides.
What You Can Do
Open the Swagger Petstore spec, the standard OpenAPI demo at petstore3.swagger.io, which is small enough to read in ful.
Find one endpoint. Count how many parameter descriptions are one sentence or less. What’s the worst description you found?
Try the same exercise on a production spec. GitHub publishes its OpenAPI description in the github/rest-api-description repository, and Stripe publishes at github.com/stripe/openapi. Fair warning: these files are enormous.
Next time: From Git Commits to Release Notes — how to translate developer commit logs into documentation your users can actually understand and act on.