API Documentation Generation
Relevant source files
The following files were used as context for generating this wiki page:The API documentation within this repository is not written manually but is auto-generated from OpenAPI specification files. This ensures that the documentation is always in sync with the API definition. The generation process is handled by a set of Node.js scripts that parse the OpenAPI specs, create corresponding content and data files, and update the site's navigation menu. The final HTML pages are then rendered by the Hugo static site generator using custom layouts and shortcodes.
Contributors should not edit the generated files directly. Instead, changes must be made to the source OpenAPI specification files located in the datadog-api-spec repository. The build process will then propagate these changes to the documentation site.
Sources: content/en/api/README.md, assets/scripts/build-api-pages.js, layouts/api/list.html
System Architecture and Data Flow
The API documentation generation is a multi-stage build process that transforms OpenAPI YAML specifications into static web pages. The process is orchestrated by Node.js scripts and executed by the Hugo static site generator.
The following diagram illustrates the high-level data flow from the source specification to the final rendered documentation page.
Build Scripts
The core of the generation process lies in the assets/scripts/build-api-pages.js and assets/scripts/build-reference-pages.js scripts. These scripts are responsible for parsing the API specifications and generating all necessary files for Hugo.
Sources: assets/scripts/build-api-pages.js, assets/scripts/build-reference-pages.js
Main Process (processSpecs)
The processSpecs function orchestrates the entire generation workflow. It iterates through a list of OpenAPI specification files (for v1 and v2 APIs) and performs a series of actions for each.
The following diagram shows the workflow within the processSpecs function.
Key Functions
The build script is composed of several key functions, each with a specific responsibility.
| Function | Description | Source File |
|---|---|---|
init() | Entry point that defines the spec files to be processed and calls processSpecs. | assets/scripts/build-api-pages.js:1003-1006 |
processSpecs(specs) | Iterates over each spec file, dereferences it, and calls other functions to generate pages, resources, and menu items. | assets/scripts/build-api-pages.js:957-999 |
createPages(...) | Creates the directory structure and _index.md files for each API tag (e.g., /api/v2/users/). | assets/scripts/build-api-pages.js:132-157 |
createResources(...) | Generates an examples.json file for each API tag, containing HTML schema tables and JSON examples for requests and responses. | assets/scripts/build-api-pages.js:164-211 |
updateMenu(...) | Reads the existing menu configuration, removes old generated entries, and adds new menu items for each API tag and operation. | assets/scripts/build-api-pages.js:19-124 |
schemaTable(...) | Recursively traverses an OpenAPI schema object and generates an HTML table representing the schema's structure, types, and descriptions. | assets/scripts/build-api-pages.js:840-877 |
filterExampleJson(...) | Recursively traverses an OpenAPI schema object to build a JSON example for a request or response body. | assets/scripts/build-api-pages.js:683-712 |
createTranslations(...) | Extracts user-facing strings like tag names, descriptions, and summaries into JSON files for internationalization. | assets/scripts/build-api-pages.js:880-928 |
Generated Assets
The build scripts produce several types of files that are consumed by Hugo.
Content Pages (_index.md)
For each tag in the OpenAPI spec (e.g., "Users", "Metrics"), the createPages function generates a directory and an _index.md file. This file contains Hugo front matter that defines the page title.
- Path:
content/en/api/<version>/<tag-slug>/_index.md - Example:
content/en/api/v2/users/_index.md
Sources: assets/scripts/build-api-pages.js:132-157
Data Files (examples.json)
The createResources function generates an examples.json file within each tag's directory. This file is crucial as it contains pre-rendered HTML for schema tables and structured JSON for request/response examples, which are used by the Hugo templates.
The structure of examples.json is as follows:
{
"operationId_1": {
"request": {
"json_curl": { /* JSON for curl example */ },
"json": { /* JSON for language-specific examples */ },
"html": "<!-- HTML table for request schema -->"
},
"responses": {
"200": {
"json": { /* JSON for 200 response example */ },
"html": "<!-- HTML table for 200 response schema -->"
},
"403": {
/* ... */
}
}
},
"operationId_2": { /* ... */ }
}
Sources: assets/scripts/build-api-pages.js:164-211, assets/scripts/build-api-pages.js:209-210
Menu Configuration
The updateMenu function modifies config/_default/menus/api.en.yaml to dynamically build the left-hand navigation menu for the API section. It adds entries for each API tag and sub-entries for each operation (endpoint) within that tag.
Sources: assets/scripts/build-api-pages.js:19-124
Hugo Templates and Rendering
The generated files are rendered into the final static site by Hugo using a set of specific templates.
Page Rendering Sequence
The following diagram shows the sequence of events when a user navigates to an API documentation page.
layouts/api/list.html
This is the primary layout file for an API section page (for example, /api/latest/users). Its main responsibilities are:
- Loading the dereferenced API specification for the current version.
- Filtering the API paths to find operations that match the current tag.
- Iterating over the matched operations and calling the
openapi-ref-docsshortcode for each one to render its documentation block.
Sources: layouts/api/list.html:20-33
layouts/shortcodes/openapi-ref-docs.html
This shortcode is responsible for rendering the documentation for a single API operation. It displays:
- The operation's summary (as the title) and description.
- A table of parameters (path, query, header, etc.).
- A tabbed interface for code examples (cURL, Python, Go, etc.).
- The request body schema table and example JSON, loaded from the
examples.jsonfile. - A list of possible responses, each with its schema table and example JSON, also loaded from
examples.json.
The shortcode dynamically retrieves the pre-generated HTML for schema tables and the JSON for examples from the examples.json file corresponding to the operation's operationId.
Sources: layouts/shortcodes/openapi-ref-docs.html:100-111, layouts/shortcodes/openapi-ref-docs.html:138-144