API reference documentation is the human-readable account of an API’s operations that consumers consult on a developer portal. Generating it from an OpenAPI definition gives the reference and other generated artifacts a common source. The reference is useful only if that definition stays aligned with the live API. section 6.0 section 6.1
When the reference and API disagree
Suppose the reference marks `keywords` as mandatory in the response from `GET /v1/catalog/products/{id}`, but the live endpoint omits it. A developer may have missed the field while implementing the service, or changed the code without updating the definition. Republishing documentation from the unchanged definition would preserve the discrepancy; the implementation and definition must first be reconciled. section 6.1
To publish a reference from an OpenAPI definition treated as the source of truth:
- Generate static HTML with `redocly build-docs product-catalog-v1-0.oas.yaml --output dev-portal/reference.html`. section 6.2.3
- Serve the `dev-portal` directory with `http-server --port 9000`, then open `http://localhost:9000/reference.html` to inspect the rendered operations. section 6.2.3
- When the definition changes, regenerate the HTML from the updated file and inspect the result. An updated product response, for example, shows `reviewRating` and `numberOfReviews` after republishing. section 6.2.5
A code-first workflow can instead generate the OpenAPI definition from application code, then generate the reference and client SDKs from that definition. Either way, repeatable artifact generation belongs in the delivery pipeline rather than an ad hoc publishing process. Documentation also needs human review: consumers should be able to understand an API from its definition and supporting guides without a meeting to explain it. section 6.3 section 8.0 section 5.5.5
