The first time I asked an engineer for read access to our OpenAPI spec, they looked at me sideways. PMs don't review API specs, the look said. PMs review designs.
I started reviewing specs anyway. Not in a "let me approve the architecture" way; I'd lose that fight and deserve to. I review them because every adoption number I'm accountable for traces back to the spec. Time-to-first-successful-call. Support ticket volume on integration questions. Whether a dev abandons during onboarding. Those metrics live in the UI of the API, and the UI of the API is the OpenAPI document.
Here's the short list of what I look for, in roughly the order I scan a new spec.
1. Are the descriptions actually useful, or just present?
Most spec linters check whether description fields exist. That's the wrong bar. "Returns user data" is technically a description; it's also useless. I read 5–10 random operation descriptions and ask: could a developer who's never seen this API write a correct call from the description alone?
The good ones answer three questions: what does this endpoint do, what parameters are non-obvious, and what happens on the common error case. Anything less is a checkbox masquerading as documentation.
2. Are there examples on the things that need them?
Request bodies, response schemas, complex parameters. Without examples, a developer either reads every field definition top to bottom or guesses. Both are failure modes. Auto-generated examples (from the schema) are better than nothing; they at least show shape. Hand-written examples with realistic values are dramatically better because they show semantics, not just types.
This is the single highest-signal addition you can make to a spec. Nothing else on this list pays back as fast.
3. Is the naming consistent enough to pattern-match?
Specs that grow over multiple teams develop accents. Some endpoints use snake_case parameters, others use camelCase. Some use /users/{id}, others use /user/{id}. Some use limit/offset for pagination, others use page/pageSize.
Each inconsistency on its own is small. Together they force a developer to re-learn the pattern at every endpoint. That's where the onboarding clock ticks.
I keep a notebook page with the conventions on each API I work on. When a new endpoint goes in, I check it against the notebook. If it deviates, the question is "do we want to be inconsistent here, or did we forget?". Most of the time the answer is "we forgot".
4. Is the auth story one story, or three?
A spec that declares one auth scheme and uses it across every endpoint is easy. A spec with three security schemes, used in different combinations across different endpoint groups, is a maze. Technically valid OpenAPI. Practically a support-ticket factory.
When I review a new spec, I look at how many security blocks are declared at the document level vs. overridden per-operation. The more overrides, the more the developer has to think about auth as a per-call decision instead of a setup-once concern. That's a UX bug.
5. Do the errors share a shape?
This one's harder to spot but matters more than people think. If your 400 response is { "error": "..." } on one endpoint and { "message": "...", "details": [...] } on another, developers writing error-handling code can't write one catch block. They write five. Eventually they stop and just check status code, and everything more nuanced than "is this a 4xx" gets lost.
I look for a shared error schema referenced from every error response. Bonus points if there's a stable code field a developer can switch on. Without one, your error model is decorative.
What I don't review
I don't review whether REST is the right protocol. I don't review whether to use OAuth 2.0 vs API keys. I don't argue about HTTP verbs at the level of "should this be a PATCH or a PUT". Those are engineering calls and I'd lose those arguments faster than I'd start them.
What I'm doing isn't architecture review. It's product surface review. The spec is what developers experience first; if it pattern-matches cleanly and answers their questions, they integrate faster and we both win.
The unglamorous version of "developer experience"
A lot of what gets called "developer experience" in 2024 is portal design, sandbox keys, and onboarding flows. Those matter. But the cheapest, highest-leverage DX work is sitting in the spec, the thing that gets converted into SDKs and documentation downstream. Fix it there and every surface improves.
Read your spec. Not the rendered docs; the raw YAML. You'll find more than you expect.
Further reading
- OpenAPI Specification: the canonical spec (3.x) from the OpenAPI Initiative.
- Spectral: open-source OpenAPI / AsyncAPI linter. The structural-checks layer this post is the opinion layer above.
- Redocly: API documentation and governance tooling. Also ships a strong linter.
