手动维护 REST API 文档随着代码端点的演进极易发生偏差。自动化可确保你的文档保持为唯一的事实来源，在构建步骤中自动更新。

docmd 通过 @docmd/plugin-openapi 或自动化的构建前 Markdown 生成为 OpenAPI / Swagger 规范提供原生渲染。

配置

在 docmd.config.json 中启用 OpenAPI 渲染：

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

自动化的构建前 Markdown 管道

或者，在运行 docmd build 之前将 Schema 编译为 Markdown：

{
  "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"
  }
}

优化 API 布局

API 参考包含较宽的参数表格和响应载荷。在页面 frontmatter 中使用 layout: "full" 以赋予最大水平宽度：

---
title: "REST API 参考"
layout: "full"
---