OpenAPI 插件将 OpenAPI 3.x 规范文件转换为结构化的 API 参考页面——在构建时渲染，无需客户端 JavaScript，无需第三方依赖。每个端点、参数、请求体和响应都转换为语义化 HTML 表格。

安装

docmd add openapi
# 或手动安装：
npm install @docmd/plugin-openapi

在您的配置中启用：

export default defineConfig({
  plugins: {
    openapi: {}
  }
});

使用方法

在任何 Markdown 页面中使用带 openapi 语言标签的围栏代码块嵌入 OpenAPI 规范：

### 实时示例

```openapi
assets/docmd-api.json
```

渲染结果

路径相对于您的 src 目录解析。支持 JSON 和 YAML 格式。YAML 需要安装 js-yaml：

npm install js-yaml

渲染内容

对于规范中的每个路径和 HTTP 方法，插件渲染：

• 方法徽章 — 颜色编码（GET、POST、PUT、PATCH、DELETE）
• 路径 — 完整端点路径
• 摘要和描述 — 来自操作对象
• 参数表格 — 名称、位置（path、query、header、cookie）、类型、必填标志、描述
• 请求体表格 — 带类型和默认值的模式属性
• 响应表格 — 带描述和响应模式类型的状态码
• 已弃用通知 — 标记为 deprecated: true 的操作内联标注

支持的 OpenAPI 功能

配置

OpenAPI 插件可以在您的 docmd.config.js 中配置：

export default defineConfig({
  plugins: {
    openapi: {
      info: true,           // 显示 API 标题和版本标题
      download: true,       // 在 UI 中提供“下载 JSON/YAML”链接
      summaryOnly: false,    // 仅显示摘要，隐藏参数/响应
      allowRawHtml: false    // 允许在描述中使用 HTML（请谨慎使用）
    }
  }
});

页面级控制

通过 frontmatter 为特定页面禁用插件：

---
title: "内部说明"
plugins:
  openapi: false
---