OpenAPI & Docs Generation
Relevant source files
The following files were used as context for generating this wiki page:
The Crucible project provides specialized generators to produce human-readable documentation and machine-readable API specifications from a centralized service model. The documentation generator outputs a complete API reference in Markdown format compatible with mdBook, while the OpenAPI generator creates standard JSON documents for RESTful integration.
These generators ensure that API documentation remains synchronized with the implementation. They support complex features such as multi-release versioning, audience-based filtering (internal vs. external), and integrated SDK descriptions.
Sources: crates/crucible-codegen-docs/src/lib.rs, crates/crucible-codegen-openapi/src/lib.rs, crates/crucible-cli/src/main.rs:218-245
Markdown API Reference
The Markdown generator creates a comprehensive documentation site. It organizes content into an overview, operation pages, and data type definitions.
Reference Structure
The generator produces a structured set of files under a src/ directory, following the mdBook layout.
| File/Directory | Description |
|---|---|
SUMMARY.md | The table of contents for the documentation site. |
index.md | The service overview, including protocol, auth, and errors. |
operations/ | Individual Markdown files for every service operation. |
shapes/ | Documentation for every data type (structures, enums, etc.). |
releases.md | A list of every supported release and changelogs. |
llms.txt | A special index optimized for LLM agents. |
describe.json | The full API reference represented as raw data. |
Sources: crates/crucible-codegen-docs/src/markdown.rs:214-332, crates/crucible-codegen-docs/src/lib.rs
Documentation Generation Flow
The generator projects the service model based on the target audience before creating documentation pages. Internal items are filtered out or marked with an "Internal" badge depending on the projection.
Sources: crates/crucible-codegen-docs/src/markdown.rs:163-176, crates/crucible-cli/src/main.rs:658-675
Multi-Release Versioning
Crucible supports documenting multiple supported releases of an API side-by-side.
- Release Directories: Each release can be generated into its own directory (e.g.,
v1/,v2/). - Release Banners: Pages belonging to older releases display a banner indicating the documented version and providing a link to the current release's reference.
- Upgrade Guides: The system generates Markdown guides explaining the changes required to move from one release to another.
- llms.txt Integration: The root
llms.txtfile indexes every versioned reference to allow agents to discover the release history.
Sources: crates/crucible-codegen-docs/src/markdown.rs:37-77, crates/crucible-build/src/docs_output.rs:56-70
OpenAPI 3.1 Generation
The OpenAPI generator translates the Crucible model into an OpenAPI 3.1 JSON document. This allows the service to be used with standard tools like Swagger UI or automated client generators.
OpenAPI Configuration
The generator accepts specific options to customize the output document.
| Option | Type | Description |
|---|---|---|
endpoint | Option<String> | The API server URL, including deployment path prefixes. |
Sources: crates/crucible-codegen-openapi/src/lib.rs, crates/crucible-cli/src/main.rs:240-245
Generation Logic
The generation process requires the service to meet specific capabilities, such as NonBlobPayload or MediaTypeHeaders, which the generator uses to construct valid OpenAPI paths and schemas.
Sources: crates/crucible-cli/src/main.rs:709-722, crates/crucible-codegen-openapi/src/lib.rs
SDK and Agent Metadata
Crucible documentation includes specific artifacts for developers and automated coding agents.
SDK Descriptions (sdks.json)
When configured, the documentation generator includes an sdks.json file. This file describes the available SDKs for the service, including their package names, installation commands, and language-specific method names for operations.
Sources: crates/crucible-build/src/docs_output.rs:33-41, crates/crucible-cli/src/main.rs:680-696
Agent Instructions (AGENTS.md)
Every generated SDK package carries an AGENTS.md file. This file provides terse, exact instructions for coding agents. It specifies:
- Exact package and import names to prevent agent hallucinations.
- Client construction and authentication examples.
- Rules for pagination and error handling.
- Idempotency behaviors for specific operations.
Sources: crates/crucible-codegen-common/src/guide.rs:434-547
Summary
The OpenAPI and Docs generation system in Crucible provides a unified way to publish service contracts. By deriving Markdown references, OpenAPI specifications, and agent-optimized instructions from a single source of truth, the project ensures consistency across all documentation formats. Features like multi-release support and audience-specific projections make it suitable for complex, evolving APIs used by both internal and external consumers.
Sources: crates/crucible-codegen-docs/src/lib.rs, crates/crucible-codegen-openapi/src/lib.rs, crates/crucible-codegen-common/src/guide.rs