使用 Spring REST Docs 生成 Swagger 客户端

Posted 2023-03-28

【中文标题】使用 Spring REST Docs 生成 Swagger 客户端

【英文标题】：Swagger client generation with Spring REST Docs

【发布时间】：2017-08-06 11:06:18

【问题描述】：

我看过这个 Spring REST Docs - video

我们正在做 Spring boot 项目，并使用 springfox 库来生成 Swagger-ui 和 swagger 文档，如 here 所述

我们喜欢 Spring Rest 文档可以为生成 REST API 文档所做的事情，以及我们不必在控制器代码中添加像 @ApiResponse 或 @ApiOperation 这样的招摇注释。而且文档现在与代码一起存在这一事实。

但是如果使用 Spring Rest 文档，我们将错过为我们的 API 自动生成的 Swagger-UI（当我们使用 swagger 集成时）。

Spring REST 文档是否可以生成像 Swagger UI 这样的测试 UI。

【参考方案1】：

这很直接违背了 Spring REST Docs 的设计理念和意图。它的主要目标之一是文档与单元测试相关联，因此即使您在 REST 合约中进行逻辑或签名更改，您也知道您的文档是坚如磐石的。

此外，您链接到的视频还提供了一些示例，说明自动文档生成如何产生大量不受欢迎的非预期输出。

因此，您可以选择做更多的工作以获得更好的文档，或者执行全自动选项以节省时间并获得可行但质量较低的文档。这是您的首要任务。

【讨论】：

如果 swagger 规范是由 Spring REST Docs 本身生成的，我不明白为什么它会违背 Spring REST Docs 的意图。如果测试失败，则不会生成任何文档、swagger 规范或 swagger ui。

不是常规的单元测试，而是您必须为 RestDocsAPI 编写的特定测试。这就是您配置 SpringRestDocs 的方式，它拥有一组特定的测试，每个字段都有一个条目。如果一个或多个字段发生更改并且未反映在指定的 Spring RestDocs 测试中，它将停止构建，因为您的文档不再与您的 REST 合同同步。

【参考方案2】：

这个项目从 Spring REST Docs 生成一个 OpenAPI 规范。

https://github.com/ePages-de/restdocs-api-spec