Redocly & OpenAPI Integration
Relevant source files
The following files were used as context for generating this wiki page:
The CircleCI documentation platform integrates API reference documentation into the main static site generated by Antora. This integration provides two distinct versions of API documentation: a static version (v1) and a dynamically generated version (v2) built from a live OpenAPI specification.
The system utilizes the Redocly CLI to transform OpenAPI definitions into interactive, high-quality HTML documentation. This process is managed via a Gulp-based build pipeline that handles fetching, patching, and bundling the API specifications before final rendering.
Sources: API_DOCS_INTEGRATION.md:1-12, README.md:38-51, gulp.d/tasks/build-api-docs.js:1-20
Architecture and Build Pipeline
The API documentation build process is orchestrated through a specialized Gulp task that runs sequentially to ensure both documentation versions are correctly integrated into the final site structure.
API v2 Build Pipeline
The v2 documentation follows a sophisticated multi-step pipeline to ensure the "live" documentation remains current and enriched with developer-friendly features like code snippets.
The diagram shows the sequential steps taken to transform the raw CircleCI OpenAPI JSON into the final interactive documentation.
Sources: gulp.d/tasks/build-api-docs.js:90-190, API_DOCS_INTEGRATION.md:39-47
Implementation Details
The build system utilizes a temporary directory (build/temp-api-v2) to store intermediate files during processing to maintain a clean workspace.
| Stage | Tool/Utility | Description |
|---|---|---|
| Fetch | curl | Downloads the latest spec from https://circleci.com/api/v2/openapi.json. |
| Bundle | @redocly/cli | Resolves $ref pointers and removes unused components to optimize file size. |
| Snippets | httpsnippet | Injects code samples for cURL, Node.js, Python, Go, and Ruby. |
| Patch | jq | Merges custom overrides from openapi-patch.json. |
| Lint | @redocly/cli | Validates the final specification against quality rules. |
| Build | @redocly/cli | Generates the index.html using a custom Handlebars template. |
Sources: gulp.d/tasks/build-api-docs.js:100-180, API_DOCS_INTEGRATION.md:88-92
Configuration and Customization
The integration relies on several configuration files to control the appearance and content of the API documentation.
JSON Patching System
Developers can modify the live API specification without changing the source at CircleCI by editing openapi-patch.json. This uses jq to perform a deep merge of the patch file into the fetched OpenAPI JSON.
Sources: API_DOCS_INTEGRATION.md:68-85, gulp.d/tasks/build-api-docs.js:203-233
Redocly Settings
The redocly.yaml file (though noted as currently unused in some build scripts) is intended for styling and configuration. The build command specifically references it along with a custom template:
npx @redocly/cli build-docs build/temp-api-v2/openapi-final.json \
--output build/api/v2/index.html \
--config redocly.yaml \
--template custom-template.hbs \
--title "CircleCI API v2 Documentation"
Sources: gulp.d/tasks/build-api-docs.js:156-163, API_DOCS_INTEGRATION.md:61-66
Navigation and UI Integration
API documentation is integrated into the site's layout through the Antora UI bundle and component navigation.
Component Access
- Header Dropdown: A "API Reference" button in the site header provides links to
/api/v1/and/api/v2/. - Sidebar Navigation: Component explorer navigation includes links in the reference sections.
- Content Links: Relative paths are used within standard documentation pages to point to the API directories.
The sequence diagram illustrates how a user interacts with the main site UI to access the integrated Redocly documentation.
Sources: API_DOCS_INTEGRATION.md:49-58, gulp.d/tasks/build-api-docs.js:12-18
Development and Testing
The project provides scripts to validate the integration and dependencies before a full site build.
Test Setup Script
The archive/scripts/test-setup.sh script performs the following validations:
- File Integrity: Checks for
api-spec.yaml,redocly.yaml, and the Gulp task file. - Dependency Check: Verifies
node_modules. - Spec Validation: Runs
redocly linton the specification. - Build Test: Executes
npm run build:api-docsand verifies the output file size.
Sources: archive/scripts/test-setup.sh:1-60, README.md:43-51
Key Commands
| Command | Purpose |
|---|---|
npm run build:api-docs | Executes the API build pipeline in isolation. |
npx @redocly/cli lint [path] | Manually validates an OpenAPI specification. |
gulp build:api-docs | The underlying Gulp task for API integration. |
Sources: API_DOCS_INTEGRATION.md:95-103, DEVELOPMENT.md:58-62
Summary
The Redocly and OpenAPI integration provides a dual-versioned API reference system. API v1 remains a stable static asset collection, while API v2 leverages a sophisticated Gulp pipeline to fetch live data, apply custom patches, and generate an interactive developer experience using Redocly CLI. This system ensures the documentation stays synchronized with the live API while allowing local overrides and styling.
Sources: API_DOCS_INTEGRATION.md:1-20, gulp.d/tasks/build-api-docs.js:1-15