在关于 API 优先的理论篇中，提到了 API 应该采用语言无关的传输方式，以方便服务之间的互操作， 如 JSON、XML 或 Protobuf 等。这只是第一步，对于 API 来说，更重要的一点是让 API 的使用者 可以方便的知道该如何调用 API。比如，应该把请求发到哪个路径上，支持哪些参数，请求的内容格式是什么样的，响应的结果又是什么格式。

在早期的时候，并没有一个统一的规范来描述 API，而是依靠不规范的文档来说明。直到 Swagger 和 OpenAPI 文档规范的出现，才解决了这个问题。OpenAPI 规范从 Swagger 发展而来，由 Open API Initiative 负责维护。目前最新的版本是 3.1.0。OpenAPI 文档可以使用 YAML 或 JSON 来描述。

OpenAPI 规范自身比较复杂，涉及到 API 相关的方方面面。其中最重要的部分，是对 API 中的每个请求路径进行描述。每个路径可以有多个操作，对应于不同的 HTTP 方法。对于每个操作，需要详细描述 HTTP 请求的路径、参数、请求内容格式和响应内容格式。OpenAPI 文档实际上就是 HTTP 操作的描述的集合。除了操作之外，OpenAPI 文档还包含一些辅助信息，包括基本信息、联系方式、授权协议、 访问控制和服务器等。

设计 API 的过程实际上就是编写 OpenAPI 文档的过程，最终的结果是一个被各方认可的 OpenAPI 文档。后续的开发工作基于这一个 OpenAPI 文档来进行。

由于 OpenAPI 规范比较复杂，建议使用图形化工具来编辑，推荐使用 Stoplight Studio。