Manually maintaining REST API documentation is prone to drift as code endpoints evolve. Automation ensures your documentation remains the single source of truth, updated automatically during build steps.

docmd provides native rendering for OpenAPI / Swagger specifications via @docmd/plugin-openapi or automated pre-build Markdown generation.

Configuration

Enable OpenAPI rendering in docmd.config.json:

{
  "plugins": {
    "openapi": {
      "spec": "./schemas/openapi.json",
      "route": "/api/reference"
    }
  }
}

Automated Pre-Build Markdown Pipeline

Alternatively, compile schemas to Markdown before running docmd build:

{
  "scripts": {
    "docs:generate-api": "npx widdershins --search false openapi.yaml -o docs/api/reference.md",
    "docs:build": "npm run docs:generate-api && npx @docmd/core build"
  }
}

Optimising API Layouts

API references contain wide parameter tables and response payloads. Use layout: "full" in page frontmatter to grant maximum horizontal width:

---
title: "REST API Reference"
layout: "full"
---