Current
API reference sources and utility containers
How Doxa builds the REST API reference for a generated site from a spec file or from code
Overview
When Doxa generates a docs site for a project with a REST API, the API reference comes from one of two sources. Both routes produce the same reference surface, so the rest of the generation, including page writing, navigation, and rendering, works the same way either way.
| Route | Source Doxa reads | What the reference contains |
|---|---|---|
| Spec route | An OpenAPI 3.0, 3.1, or 3.2 file, or a Swagger 2.0 file, in the connected repository | The endpoints the spec declares |
| Model route | Route handlers and validation schemas in the code | The endpoints that analysis finds in the code |
Spec route
Doxa uses the spec route when the connected repository contains a supported OpenAPI or Swagger file. The spec replaces the REST surface that code analysis would otherwise produce. Endpoints that exist only in code and are not declared in the spec do not appear in the reference.
Model route
Doxa uses the model route when no spec file passes. Analysis reads the route handlers and validation schemas and builds the endpoint list from what it finds. Each endpoint gets its own reference page, with its parameters and responses.
Endpoint coverage
Doxa does not cap the number of endpoint pages. Every endpoint in the reference gets its own page.
The generation budget limits only the guide, concept, and workflow pages that Doxabot writes as prose. It does not limit endpoint pages.
What the reference documents
The Doxabot instructions for your project decide what the REST and SDK reference documents. Set them from the Generations and Doxabot Instructions page. Three controls apply:
| Control | Effect |
|---|---|
| API reference page type | Turned on by default. When it is off, the generation keeps no API reference, and a new plan does not add a reference page. |
| Do not document paths | Glob patterns for folders or files. An endpoint is left out only when every path of its evidence is under one of these patterns. A folder pattern also covers the files inside it, so apps/admin covers apps/admin/stats.ts. |
| Owner rules | Plain-language rules such as "Do not document the admin endpoints." Doxabot leaves out an endpoint only when your instructions say so. |
Note:
A project's category, such as api or platform, does not remove endpoints from the reference. Whether an endpoint looks internal does not remove it either. Only your Doxabot instructions remove endpoints or exports.
Isolated jobs during generation
Some generation steps, such as reading an OpenAPI or Swagger file, run in isolated jobs. Each job does one task for one generation and then stops:
A job has one fixed task. Its input cannot select other code.
A job receives no secrets and has no network access.
A job runs in its own instance for each generation run.
You do not configure these jobs, and they do not change what the reference documents. Your control over the reference is the set of Doxabot instructions described above.