Reference design, OpenAPI, examples, developer journeys and interface contracts.
A technically valid request is not automatically a useful example. Choose examples that expose the mental model, show realistic values and let a developer predict what to do next. An example copied from a schema can be syntactically correct and still teach nothing.
Good authentication docs explain the whole credential lifecycle: obtaining access, sending credentials, rotating them and diagnosing failure. Explain prerequisites, roles, environments and credential issuance before the first HTTP request.
An error reference is useful only when it helps a developer identify the condition, understand the response and choose a safe next action. Describe the condition that triggers an error, not only a status code and message.
Good API documentation combines machine-readable contracts with human explanations, runnable examples and explicit error behavior. REST API documentation has two audiences at once: machines and people.
An OpenAPI description can generate accurate reference structure, but developers still need concepts, task flows, authentication guidance, examples and failure recovery that a schema alone cannot explain. OpenAPI is excellent at describing operations, parameters, request and response shapes, status codes and reusable schemas.