TDC：文档，解释 3.0 规范第 5 部分

随着 OpenAPI 规范 3.0 版本即将进入 beta 候选阶段，本系列文章旨在从技术开发者社区 (TDC) 的角度提供对变更内容及其方式的见解。本系列文章的前几篇文章描述了 规范演进的背景和理由，以及一些 结构变化、请求参数，以及 协议和负载。

文档

围绕先前版本的 OpenAPI 规范发展起来的各种工具表明，这些开发人员可以访问构建这些工具所需的信息。3.0 版本不仅应该延续这种成功，而且随着 TDC 和社区成员的参与度提高，规范应该比以前更易于访问、更清晰、更明确。

目录

由 Rob Dolin 在规范中添加了一个目录，以便为新读者提供快速概述文档结构，并将使他们更容易访问规范参考的相关部分。随着规范更改逐渐稳定，文档工作将加快步伐，规范也将更容易访问。

通用标记

2.0 规范使用 GitHub 风格的 Markdown (GFM) 来提供服务的富文本描述。不幸的是，GFM 本身没有正式规范，而且它的一些功能仅适用于托管在 GitHub 上的内容。出于这个原因，OpenAPI 规范的 3.0 草案 已采用 CommonMark 格式，这将使工具在渲染 Markdown 时更加一致。CommonMark 与 GFM 大致兼容，因此此更改对现有文档的影响很小。而且，凭借 CommonMark 带来的详细规范，更高的精确度将减少歧义，总体上应该是利好。

下一篇文章将讨论社区提出的其他杂项未决问题。

—
关于作者
Darrel Miller 是微软 Azure API Management 的高级软件开发工程师。Darrel 是 OpenAPI 规范技术开发者社区的成员。您可以在 Twitter 或他的博客 Bizcoder 上关注他。