API References
How DevDocs turns OpenAPI specs into browsable, testable reference docs.
An api_reference connects an OpenAPI specification to generated documentation pages, request examples, playground execution, and SDK-ready snippets.
Reference lifecycle
Import the specification
Start with a local fixture, repository file, or approved external URL.
Validate and normalize
Bundle references, validate OpenAPI syntax, and produce stable operation identifiers.
Generate reference pages
Create a page tree that fits the existing DevDocs navigation model.
Enable the playground
Allow safe demo requests first, then add approved external execution paths.
Playground expectations
The DevDocs playground should eventually support:
- endpoint search and operation navigation
- parameter and request-body editing
- generated code snippets
- response status, headers, body, and timing
- redacted shareable request state
- replay for recent requests
- clear failure messages for auth, validation, CORS, timeout, and proxy errors
V1 boundary
V1 should prove generated OpenAPI references with a DevDocs demo fixture and same-origin execution. External proxying, credential storage, and customer-import workflows should land only after the security model is explicit.