Spring REST Docs 与 OpenAPI 的比较
1、概览 Spring REST Docs 和 OpenAPI 3.0 是为 REST API 创建 API 文档的两种方法。
在本教程中，我们将探讨它们的相对优缺点。
2、前世今生 Spring REST Docs 是由 Spring 社区开发的一个框架，用于 为RESTful API 创建准确的文档。它采用了测试驱动的方法，文档可用 Spring MVC tests、Spring Webflux 的 WebTestClient 或 REST-Assured 形式编写。
运行测试的结果会生成 AsciiDoc 文件，可以使用 Asciidoctor 将它们组合在一起，生成描述 API 的 HTML 页面。由于它遵循 TDD 方法，Spring REST Docs 自动带来了许多优势，例如减少代码错误、减少重复工作和更快的反馈周期等。
而，OpenAPI 是一种诞生于 Swagger 2.0 的规范。截至本文撰写时，其最新版本为 3.0，并有许多已知的 实现。
与其他规范一样，OpenAPI 也为其实现制定了一些基本规则。简而言之，所有 OpenAPI 实现都应该以 JSON 或 YAML 格式的 JSON 对象生成文档。
还有 许多工具 可以接收 JSON/YAML，并输出 UI 界面来可视化和导航 API。这在验收测试时非常有用。在这里的代码示例中，我们将使用 Springdoc - 一个用于 OpenAPI 3 和 Spring Boot 的框架。