@docmd/plugin-openapi 插件将 OpenAPI 3.x 规范文件（JSON 或 YAML）转换为结构化的、可搜索的 API 参考页面。遵循 docmd 的“零 JS”运行时理念，每个端点、参数表格和 Schema 模型都会在构建处理期间被编译为静态 HTML。

配置选项

在 docmd.config.json 中配置全局 OpenAPI 渲染参数：

全局配置示例

{
  "plugins": {
    "openapi": {
      "info": true,
      "download": true,
      "summaryOnly": false
    }
  }
}

用法与语法

使用带有 openapi 语言标记的围栏代码块嵌入 OpenAPI 规范。请指定源于您文档源码根目录的相对文件路径：

```openapi
assets/openapi.json
```

实时渲染效果

以下是 assets/docmd-api.json 的实时交互式渲染示例：

规范输出解析

插件会解析并渲染：

• HTTP 方法徽章: 颜色编码徽章 (GET, POST, PUT, PATCH, DELETE)。
• 端点路径: 带参数的路径字符串。
• 参数表格: 名称、位置 (path, query, header, cookie)、数据类型、必填标志以及描述。
• 请求与响应模型: 包含字段类型、数据格式、约束与默认值的结构化 Schema 表格。
• 示例与请求体载荷: 多格式请求体与响应载荷示例 (application/json, application/xml 等)。
• 隔离 Schema 表格横向滚动: 复杂嵌套的 Schema 表格可在 .oa-table-wrap 容器内独立横向滚动，避免撑开全页面视口。
• 弃用警告横幅: 针对标记有 deprecated: true 的端点提供内联警告。

技术兼容性