Generating an API reference from an OpenAPI schema

Overview

Some API reference pages in cld_docs are generated directly from an OpenAPI schema.yml file (instead of being written manually in markdown).

In this flow, the markdown page is intentionally minimal, and the page content is rendered from the schema file path configured in config/locales/en.yml.

How schema-based API references work in cld_docs

• The doc page file in app/views/documentation/ contains front matter only.
• The page’s entry in config/locales/en.yml includes a schema: field that points to the schema file.
• The schema files live in public/documentation/schemas/<api-name>/ in this repo.

Examples:

• The Provisioning API reference uses:

  • config/locales/en.yml → schema: schemas/provisioning-api/schema.yml
  • Schema file → public/documentation/schemas/provisioning-api/schema.yml

• The Analyze API reference (Beta) uses:

  • config/locales/en.yml → schema: schemas/analysis-api/public-schema.yml
  • Schema file → public/documentation/schemas/analysis-api/public-schema.yml

Add a new schema-based API reference page

1) Add the schema files to the repo

1. Create a new folder under public/documentation/schemas/.
2. Add your OpenAPI schema file as schema.yml (or public-schema.yml if that’s the file you want to render).

For example:

• public/documentation/schemas/<api-name>/schema.yml

2) Create the doc page (front matter only)

1. Create a new page under app/views/documentation/, for example:
   • app/views/documentation/<page_id>.html.md
2. Add standard front matter (categories/module/etc). You generally don't add the schema path here.

3) Configure the schema path in config/locales/en.yml

In config/locales/en.yml, under the page’s entry (same key as the filename / page id), add a schema: line pointing at the schema file (relative to public/documentation/).

Example:

4) Add the page to the relevant menu

Add your page id to the relevant menu JSON under app/menus/ so it appears in the TOC.

Collaboration workflow with R&D (public-interfaces as the collaboration hub)

The OpenAPI schema content is typically owned and maintained by R&D, but docs frequently needs to iterate on:

• Endpoint descriptions and summaries
• Request/response examples
• Parameter naming/format consistency
• Tagging/grouping and ordering (where supported)

In practice, teams collaborate through a shared “schema hub” repo (often called public-interfaces), even if R&D develops the schema elsewhere during implementation.

The expected PR loop

• R&D → public-interfaces → cld_docs

  • R&D updates the schema in their working location during development.
  • When ready, they merge those changes into public-interfaces.
  • An automation flow opens a PR into cld_docs with the updated schema content.
  • Docs reviews the PR in cld_docs and merges when ready.

• Docs → public-interfaces → cld_docs

  • If docs needs to improve descriptions/examples, make the change in cld_docs only for local review, but open a PR against public-interfaces with the same change.
  • Once that PR is merged to public-interfaces, the same automation flow should open a corresponding PR back into cld_docs.

When it’s okay to edit schema files directly in cld_docs

You may temporarily edit a schema file in cld_docs to preview how a change renders (or to quickly protect customers from incorrect/undesired output), but you should treat public-interfaces as the place the change is negotiated and make sure the equivalent PR exists there.

Overlays (optional pattern)

Some APIs may use an “overlay” concept to add doc-specific content on top of a base schema (for example: intros, descriptions, or examples) without requiring R&D to constantly sync those doc-only edits.

In this repo, you may see files like:

• public/documentation/schemas/<api-name>/overlay.yml

If you’re working on an API that already has overlays (or you want to adopt this pattern), align with the API’s owner (and the docs platform owner) on:

• Which schema file should be rendered (base schema vs a “public” composed schema)
• Where doc-only additions should live (overlay vs schema)
• How composition is performed (build step / automation)