by APIDocGen (LX AI)
Stale API docs usually mean the contract and the narrative drifted. OpenAPI best-practice guidance stresses a single source of truth and putting descriptions in source control.
I keep the OpenAPI description in the same repository as the service code. This makes the file visible to anyone who reads the source and lets version control show every change.
I place the file at docs/openapi.yaml at the repo root. The path is short, easy to find, and does not clash with generated assets.
Every edit to the API contract goes through a pull request. I require at least one approver who checks that the description matches the code changes. I also run a lint step in the CI pipeline before the PR can be merged.
I add a test suite that calls the running service and validates each response against the OpenAPI schema. If the service returns something that does not match the contract, the test fails and the team gets immediate feedback.
Integrators first notice problems when they receive an error they did not expect. Describing 4xx and 5xx shapes reduces support tickets and lets client generators produce correct error handling code.
I add a components.responses section for each client error that the API can return. Typical entries include 400 Bad Request for validation problems, 401 Unauthorized for missing or invalid credentials, 403 Forbidden for insufficient scopes, and 422 Unprocessable Entity for business‑rule violations.
Server errors are less frequent but still need documentation. I describe a generic 500 Internal Server Error response and, when applicable, a 503 Service Unavailable with a Retry-After header.
components:
responses:
ValidationError:
description: Validation failed on input fields
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
validation:
summary: Missing required field
value:
error: invalid_request
message: \"field 'email' is required\"
details:
- field: email
issue: missing
When a developer sees a clear request or response example, the time spent guessing drops dramatically. I place examples directly beside the schema they illustrate, using OpenAPI’s example or examples fields.
For simple objects I add an example value inside the schema. This shows up in Swagger UI and Redoc without extra files.
For larger payloads I keep a separate examples/ folder and reference it with $ref: ./examples/payment-request.json. This keeps the main file readable while still providing rich samples.
APIDocGen reads the OpenAPI file and creates curl, JavaScript fetch, and Python requests snippets for each operation. I store those snippets in the docs/snippets/ directory and link to them from the operation description.
A broken reference or a missing operationId can silently break client generators and documentation sites. I run a linter as part of the build pipeline and fail the build on any error.
I use Spectral with the spectral:oas ruleset because it understands OpenAPI 3.1 and lets me add custom rules for our internal conventions.
In the GitHub Actions workflow I add a step that installs Spectral via npm, then runs spectral lint docs/openapi.yaml. The step uses the continue-on-error: false setting so any problem stops the pipeline.
The linter checks that every $ref> can be resolved and that each operationId> is unique across the file. I also enforce that all paths have a summary> and a description>.
| Rule | Severity | What it checks |
|---|---|---|
| no-unresolved-ref | error | All $ref pointers must resolve |
| operation-operationId | error | Each operation must have an operationId |
| no-duplicate-operationId | error | operationId values must be unique |
| path-summary | warning | Every path item needs a summary |
| path-description | warning | Every path item needs a description |
I want to be honest about the limits of a checklist. Following these items improves the quality of your OpenAPI description, but it does not guarantee perfect documentation in every situation.
Even with a lint‑clean file and rich examples, developers may still find gaps if the API behavior changes at runtime. The checklist helps you catch many issues, but you still need to verify the live service.
Contract tests that validate responses against the schema are valuable, but they do not replace exploratory testing, performance testing, or security scanning. Treat the checklist as one layer of defense.
If the underlying API is confusing or inconsistent, no amount of documentation will make it easy to use. Spend time on clean resource modeling, clear naming, and sensible error codes before you invest heavily in docs.
An OpenAPI file can become stale if nobody notices that the code has diverged. I put in place lightweight habits that make stale files visible before they cause confusion.
I configure the CI pipeline to regenerate HTML documentation (using Redoc) after each successful build and publish the output to a static‑site host. The URL of the published docs appears in the pull request comment, so reviewers can see the rendered version instantly.
Every time a contributor modifies a handler or a data model, I ask them to open the OpenAPI file and verify that the relevant paths, parameters, and responses reflect the change. I add a reminder comment in the pull request template.
I run a nightly job that git‑diffs the OpenAPI file against the version from the previous week. If the diff shows more than thirty lines changed, the job posts a message to the team channel asking for a quick review.
I keep a written checklist next to every release that touches this topic. The list is boring on purpose: name the owner, name the evidence artifact, and name the rollback. If a step cannot produce a file, a ticket, or a log line, it is not a step — it is a wish.
| Signal | What to record | Stop-ship? |
|---|---|---|
| Unexpected write or send | Tool name, args, identity | Yes until gated |
| Missing confirmation on destructive action | Call path and bypass | Yes |
| Untrusted text treated as instruction | Source surface and resulting action | Yes for agent reach |
| Scanner clean, judgment open | Deferred items + owner | Only if core path safe |
api-docgen helps with the measurable first pass. Architecture choices, legal sign-off, and customer-facing claims still need a human owner. Treat every checklist row as decision support, not a certificate.
When a prospect asks whether the product "covers everything," I answer with the boundary: automated checks catch known patterns; novel chains and policy judgment still need review. That honesty keeps support load down and keeps the blog aligned with what the product actually does.
If you need a second opinion, pair this write-up with the references below and with your own staging reproduction. Do not skip the reproduction step just because a model wrote a confident summary.
Maintain OpenAPI (or an endpoint inventory that can become OpenAPI). Render with Swagger UI for try-it, Redoc for reading, or generate Markdown examples for READMEs.
Include 4xx/5xx shapes. Integrators fail on undocumented auth and validation errors first.
Examples cut Slack back-and-forth. APIDocGen focuses on curl / JS / Python snippets from your endpoint list.
Broken $ref or missing operationId silently break generators. Redocly CLI / Spectral are common gates.