Technical Writing
Development

Distribute API Reference from YAML Across Docs, and Apps

Olivier Carrère •
#astro#api#openapi#yaml#documentation

I’ve been experimenting with self-documenting APIs in Astro, and you can now browse the live API documentation.

Display the same information on a mobile app and on a web page from the same source.

The real magic is that everything comes from a single YAML file.

By exposing structured reference information through an API generated from YAML, you can reuse the same source of truth across multiple contexts:

One YAML File, Many Outputs

By keeping all reference information in a single YAML file, you gain a powerful distribution workflow. From this one source of truth, the data can flow into interactive API documentation, SEO-friendly HTML pages, or be accessed directly via API calls.

Display the same information on a mobile app and on a web page from the same source.

The diagram below shows how the same YAML powers multiple outputs without duplication or extra maintenance:

graph LR %% Nodes A["📄 YAML Source File"]:::topic B["📘 API Docs<br/>(OpenAPI schema)"]:::step C["🌐 Static HTML Docs<br/>(Astro build-time)"]:::step D["⚡ API Queries<br/>(fetch / curl)"]:::step B1["🖥️ Web UI"]:::substep C1["📑 Tables, Lists"]:::substep D1["📦 JSON Responses"]:::substep D2["📱 Mobile App"]:::substep %% Flows with animated links A a1@--> B A a2@--> C A a3@--> D B a4@-->|Interactive browsing| B1 C a5@-->|SEO-friendly pages| C1 D a6@-->|Live API calls| D1 D a7@-->|Consumed by clients| D2 %% Animation speeds a1@{ animation: slow } a2@{ animation: slow } a3@{ animation: fast } a4@{ animation: slow } a5@{ animation: slow } a6@{ animation: slow } a7@{ animation: slow } %% Styling classDef topic fill:#fbe9e4,stroke:#df9277,stroke-width:2px,color:#5a2e23,font-weight:bold,rx:8,ry:8; classDef step fill:#f6d1c5,stroke:#d97d61,stroke-width:2px,color:#4a241a,font-weight:bold,rx:8,ry:8; classDef substep fill:#efb9a6,stroke:#c96a52,stroke-width:2px,color:#3d1d15,font-weight:bold,rx:8,ry:8; %% Link styles linkStyle default stroke:#d97d61,stroke-width:2px;

Querying the API in Practice

You can query the API directly with JavaScript or from your terminal.

Using fetch (JavaScript)

// Fetch all oil types
fetch("https://redaction-technique.org/api/oil-types")
  .then(res => res.json())
  .then(data => {
    console.log("All oil types:", data);
  });

Using cURL (terminal)

# Get all oil types
curl https://redaction-technique.org/api/oil-types

Example JSON Output

Here’s what you’ll see when calling the API:

GET /api/oil-types

{
  "id": "oil-types",
  "title": "Oil types",
  "shortdesc": "You will find below the recommended oil types.",
  "properties": {
    "headers": {
      "type": "Type",
      "value": "Brand",
      "description": "Use"
    },
    "rows": [
      {
        "type": "Primary oil",
        "value": "A1X",
        "description": "One-cylinder engines"
      },
      {
        "type": "Secondary oil",
        "value": "B2Z",
        "description": "Two-cylinder engines"
      }
    ]
  }
}

Why YAML as the Source of Truth?

Instead of relying on a static JSON schema, the API specification is generated directly from YAML.

This approach ensures:

By centralizing reference information in YAML, you don’t just build an API—you build a distribution engine for consistent, reusable documentation across every medium.

As explained in Strong Information Typing Without XML Overhead, the same YAML file can also be consumed at build time in Astro.
This lets you generate static tables, lists, or components—keeping pages fast, SEO-friendly, and always consistent with the live API.

← Back to Blog