How to document an API from contract to evidence
Document an HTTP API from its reviewed contract, including parameters, bodies, responses, errors and security, then verify runtime behavior separately.
Build an endpoint reference from reviewed contract evidence: identify the method and path, document every input and its serialization, describe request and response content by status code, expose security requirements and known errors, and preserve unresolved references. Then test the published examples against the deployed service, because an OpenAPI document describes a contract but does not prove runtime behavior.
Define the audience and operation identity
Start with the reader's task and the operation that supports it. Record the HTTP method, path template, short summary and stable operation identifier when one is declared. Explain what the operation is intended to do without inventing guarantees that are absent from the contract.
- Choose one operation and one reader goal.
- Copy the method and path exactly.
- Retain the declared summary and operation identifier.
- Flag a missing description for review instead of filling it with an assumption.
Document parameters with location and serialization
For each path, query, header or cookie parameter, state its name, location, required state, schema and declared serialization behavior. Provide an example only when the source supplies one or a reviewer has approved it. A path parameter is required by OpenAPI, while an optional query parameter should not be presented as mandatory.
Separate request bodies from success responses
Describe request content by media type, schema and required state. Then list success responses by status code, media type, schema and example. Keep a schema reference visible and resolve it only when the referenced component exists; silently replacing a broken reference makes the page look more certain than its source.
Show known errors and security requirements
Document every declared non-success response, including its status code, description and response body shape. RFC 9457 defines a reusable problem-details format, but do not claim an API uses it unless the contract or runtime evidence says so. List operation-level security requirements and the named schemes they depend on instead of reducing authentication to a generic lock icon.
Test the reference against the deployed service
Validate sample requests with authorized test credentials in a non-destructive environment. Compare actual status codes, content types, headers and response shapes with the contract, then record the service version and test date. Treat drift as a documentation or implementation defect to resolve; do not rewrite observed behavior as an undocumented promise.
Check the primary references
Check the source against the result
A reviewed OpenAPI 3.1 JSON document declares GET /orders/{orderId}, a required path parameter named orderId, an optional expand query parameter, bearer security, a 200 response referencing the Order schema and a declared 404 response.
The generated Markdown identifies GET /orders/{orderId}, separates the path and query inputs, lists the bearer security requirement, records the 200 and 404 responses, and keeps each resolvable component reference attached to its declared schema.
The specification does not prove that a server URL is reachable, bearer credentials work, the deployed 200 body matches the Order schema or the service returns the documented 404. Verify those runtime claims separately and preserve the date and environment of the test.
Turn a bounded OpenAPI contract into Markdown
Load an OpenAPI 3.0 or 3.1 JSON document locally, select one operation and inspect its parameters, bodies, responses, security and unresolved references.
Open API Documentation Generator