OpenAPI-Specification 规范文档的 Markdown 结构与 md2html 发布管道解析

• API设计
• 文档
• 后端

OpenAPI Specification 仓库（OAS）不仅定义了 HTTP API 的开放描述标准，其自身的规范正文（versions/*.md与src/oas.md）也有一套严格的 Markdown 编写约定，并通过 md2html 工具链转换为 W3C 风格（respec 格式）的 HTML 规范文档。本文以仓库测试夹具 basic-old.md 为骨架，逐层剖析规范文档的标题层级、版本头、conformance 章节、手写目录（TOC）处理、锚点与修订历史表格等结构约定，并结合 md2html.test.mjs 测试、spec.config.json 构建配置与真实版本文件，说明这套 Markdown 规范如何被解析、校验并最终发布。读完本文，你将理解 OAS 规范文档的书写模板、md2html 转换的行为边界，以及如何在本仓库中验证这些约定。

一、为什么规范正文需要一套 Markdown 约定

OpenAPI Specification 的"源码"是 Markdown 文档，发布物则是 HTML。从仓库结构与构建脚本可以推断出如下链路：

• 规范主源文件位于src/oas.md（由 spec.config.json 中specSrc与release.sourcePath字段指明）；
• 每个已发布版本在 versions 目录下对应一份X.Y.Z.md（如 3.2.1.md、3.1.1.md、3.0.4.md）；
• 构建时由@oai/build-infra包中的 md2html 工具把 Markdown 转成带 respec 配置的 HTML 规范页。

正因为转换是程序化的，规范正文的 Markdown 结构就必须稳定、可预测：哪些标题进入什么层级、哪个段落成为 conformance 章节、手写目录如何被丢弃、锚点如何保留，全部由约定与代码共同保证。tests/md2html/fixtures/目录下的basic-old.md（旧输入）与basic-new.md（新输入）正是用来锁定这些行为的样例，而basic-old.html、basic-new.html是它们对应的期望输出。

二、从 basic-old.md 解剖规范文档的 Markdown 骨架

basic-old.md虽然名为 fixture，其内容正是 OAS 规范正文的缩微模板。逐行分析可以看到以下几个核心结构块：

# Heading 1 Text for first chapter #### Version 30.0.1 This is the conformance section ## Table of Contents Will be removed ## Heading 2 Text for first section <a name="parameterAllowEmptyValue"/>Broken anchor ### Heading 3 Text for first subsection Version | Date --------|----------- 30.0.1 | 3001-04-01

1. 文档级标题（H1）与版本头（Version 头）

• 第一行# Heading 1对应真实文档中的# OpenAPI Specification标题（见 3.0.4.md）。
• 紧随其后的#### Version 30.0.1是版本头。在真实仓库中它的层级并不统一：早期版本使用四级标题#### Version x.y.z（如 3.0.0.md、3.1.0.md），从 3.0.4 开始改为二级标题## Version 3.0.4（见 3.0.4.md、3.1.1.md、3.2.0.md）。在输出 HTML 中，该版本头被转换为<section class="override" id="conformance">一致性章节（见 basic-old.html 第 17–18 行），正文This is the conformance section即一致性声明段。

2. 手写 Table of Contents 会被移除

## Table of Contents一节在目标 HTML 中完全不存在。原因从 respec 机制可以理解：规范页的目录由 respec 脚本根据文档标题结构自动生成（对应 HTML 中的#toc），因此手写的 TOC 必须删除以避免重复与混乱。这一点在 basic-old.html 与 basic-new.html 中均有验证：输入里的## Table of Contents / Will be removed没有出现在任何输出中。

3. 锚点（anchor）的处理

<a name="parameterAllowEmptyValue"/>Broken anchor展示了两种行为：

• 该写法对应真实规范中为关键概念插入的锚点（如3.1.1.md中大量[附录引用](#appendix-...)依赖这类目标锚点）；
• 在旧格式中它以裸<a name="..."/>出现在段落中间，HTML 输出将其转换为<span id="parameterAllowEmptyValue"></span>（见 basic-old.html 第 21 行），而新格式则要求在段内使用<a name="first-anchor"></a>并生成<span id="first-anchor"></span>（见 basic-new.html 第 20 行）。

4. 修订历史表格（Revision History）

文档末尾的 Markdown 表格是规范正文的固定收尾结构：

Version | Date --------|----------- 30.0.1 | 3001-04-01

md2html 将其转换为标准的<table><thead><tbody>结构（basic-old.html 第 24–37 行）。在真实规范中这一节是## Appendix A: Revision History，例如 3.1.1.md 的附录 A 即修订历史。从basic-new.md看，新格式还会显式标注## Appendix A: Revision History标题，使章节进入 respec 的 appendix 语义（对应 basic-new.html 中<section class="appendix">）。

三、md2html 测试如何锁定这些行为

测试位于 md2html.test.mjs，它把fixtures/下每个.md文件作为输入，运行@oai/build-infra的 md2html.js，并将输出与同名的.html期望文件做严格比对：

const expected = readFileSync(folder + entry.name.replace(".md", ".html"), "utf8"); const output = await md2html( [ "--spec-config", "spec.config.json", "--maintainers", entry.name.replace(".md", ".maintainers"), entry.name, "path/31.0.0.md\npath/30.0.1.md\npath/30.0.0.md", ], folder, ); expect(output.stdout).to.equal(expected);

从中可以提取三条关键信息：

1. 配置来源：转换依赖仓库根目录的 spec.config.json（测试中通过--spec-config传入），该文件定义了slug、shortName、titleName、abstractText、participateLinks、schemas、release等元数据（fixtures 目录下另有副本 spec.config.json，供测试独立运行）。
2. 维护者列表：通过--maintainers传入对应的.maintainers文件，例如 basic-old.maintainers 中* Foo Bar @foobar会被注入 HTML 的 respec 配置editors字段。
3. 版本列表：md2html 会收到一份已发布版本清单（path/31.0.0.md\npath/30.0.1.md\npath/30.0.0.md），用于生成 respec 配置中的otherLinks（"Other versions" 下拉项）。

因此在修改规范 Markdown 时，fixtures目录既是模板样本也是回归测试的基线：任何改变标题层级、锚点转换或表格渲染的行为都会导致测试失败。

四、真实版本文件的印证：结构与 appendix 体系

将 fixture 的骨架与真实规范对照，可以看到约定在实际文档中的规模：

• 版本头：versions/3.0.4.md在标题下直接书写## Version 3.0.4与 BCP 14 关键词说明（MUST / SHOULD / MAY 等），随后是## Introduction、## Definitions等章节（3.0.4.md）。
• Definitions 体系：basic-new.md演示了## Definitions下挂### Foo定义条目，真实文档中### OpenAPI Description、### OpenAPI Document、### Schema均按此模式组织（3.0.4.md），md2html 会为其生成<dfn>定义标记。
• 锚点与交叉引用：规范正文大量使用[See Appendix ...](#appendix-...)形式的内部链接，例如 3.1.1.md 中的"附录 E：百分号编码"、"附录 D：Header 与 Cookie 序列化"等交叉引用；这些目标锚点依赖 md2html 对<a name>/<span id>的稳定转换。
• 修订历史：真实文档以## Appendix A: Revision History收尾（3.1.1.md），与 fixture 的表格结构一一对应。

五、代码块语言与媒体类型：从 basic-new.md 看目标输出能力

basic-new.md作为"新格式"样例，展示了 md2html 对代码块语言标签的完整支持面，这也是规范正文中嵌入示例的标准做法：

这些代码块在输出 HTML 中被包装为<pre class="nohighlight"><code>，并使用 hljs 主题高亮（见 basic-new.html 第 32–103 行）。此外，basic-new.md还展示了 RFC 引用写法（如[[RFC3986]]、[[RFC9110]]），md2html 会将其转换为 bibref 引用或带 Section 链接的引用形式，而规范正文中的 BCP 14 / RFC 关键词引用（见 3.0.4.md）即属于此类。

六、Markdown 校验与发布：配置层面的支撑

除转换外，仓库还有一整套配置约束规范正文的书写质量：

• Markdown 风格规则：根目录的 spec.markdownlint.yaml 规定标题必须使用 ATX（#前缀）风格（MD003）、无序列表必须用*（MD004）、缩进 2 空格（MD007）、行宽上限 800 字符且表格不参与计数（MD013）、标题前后需空行（MD022）、允许重复标题（MD024）、允许内联 HTML（MD033）——最后一条正是锚点<a name>能合法存在的原因。
• 校验与构建命令：package.json 提供validate-markdown（oai-spec-validate-markdown）、format-markdown（oai-spec-format-markdown）、build（oai-spec-build）、test（oai-spec-test）等脚本，规范改动的合规性检查与构建发布被纳入统一命令链。
• 发布期转换：根目录 spec.config.json 的release段说明发布时会从src/oas.md生成版本文件，并对src/schemas/validation/*.yaml、tests/schema/pass、tests/schema/fail等路径做 schema 版本号重写（schemaVersionRewrite）。也就是说，Markdown 结构约定只是 OAS 发布链路的一环，与之配套的还有 schema 与示例的版本同步。

七、如何本地查看与验证这套管道

• 查看转换产物：fixtures下的.html文件是可直接打开的期望输出；tests/md2html/README.md还说明，若要以 respec 格式在本地浏览器渲染这些 HTML，可执行：

  mkdir js cp ../../node_modules/respec/builds/respec-w3c.js js/ echo "*" > js/.gitignore

  然后本地打开即可（仓库是只读的，这一步骤只涉及本地查看）。

• 运行测试：在仓库根目录执行yarn test（内部调用oai-spec-test），md2html.test.mjs会遍历 fixtures 中所有.md文件并与.html基线比对；任何与本文所述结构约定的偏差都会在此暴露。

• 学习完整模板：阅读tests/md2html/fixtures/basic-new.md（新格式）与versions/3.1.1.md、versions/3.2.1.md等真实版本正文，可以同时获得"缩微模板"与"完整成品"两个视角，是编写或审查 OAS 规范文档的首选参考资料。

结语

tests/md2html/fixtures/basic-old.md虽小，却是理解 OpenAPI-Specification 仓库"文档即代码、代码即规范"理念的最佳切入点：标题层级决定章节语义，Version头决定 conformance 章节，手写 TOC 会被丢弃，锚点与修订历史表格有固定的转换路径，而这一切都被 md2html.test.mjs 与配套的 HTML 基线牢牢锁定。对任何参与 OAS 规范维护或希望自建"Markdown 规范文档 → respec HTML"管道的团队，这套约定与测试模式都值得直接借鉴。

• API设计
• 文档
• 后端