用于 Spring Data Rest 的 Swagger 2 或 3答案

【问题标题】：Swagger 2 or 3 for Spring Data Rest用于 Spring Data Rest 的 Swagger 2 或 3
【发布时间】：2020-11-07 10:56:52
【问题描述】：

我有一个使用弹簧数据休息的弹簧启动应用程序。我在使用 swagger 提供阅读良好的 API 文档时遇到问题。我试过spring fox和springdoc，但各有问题

春狐：

我无法更改存储库的标签名称，只能更改描述
不支持投影
尚不支持openAPI3（这其实不是什么大问题）

Springdoc (https://springdoc.org/)

我无法更改标签名称和描述（@Tag 不适用于 repos）
不支持投影
同一个 repo 有 3 个标签，例如books-entity-controller、books-search-controller（带有父类的方法）和 books-property-reference-controller（带有不必要的 /{id}/{property} url 列表）

有更好的方法吗？我喜欢 spring fox 不提供多个标签，自动生成的标签名称也更好，例如书籍实体而不是书籍实体控制器。但最好是定制它或找到更好的替代方案。

【问题讨论】：

标签： swagger spring-data-rest openapi springfox springdoc

【解决方案1】：

Springdoc

我无法更改标签名称和描述（@Tag 不适用于 repos）

和

同一个仓库有 3 个标签

您可以自定义它。在控制器类级别使用以下内容。

@Tag(name = "Name of the Tag", description = "Description of the tag")

或

@Tags(value = {
    // Multiple @Tag annotations separated by comma ,
})

或方法级别的以下内容。

@Operation(tags = {"Tag 1", "Tag 2"})

记住：

类级别的@Tag 将覆盖特定类的操作级别标签。
一个类级别标签只能有 1 个值。

所以如果你需要一个控制器有多个标签，你应该把它隔离在一个不同的类中，在类级别没有@Tag。

不支持投影

我从未使用过投影。我通常使用@JsonIgnore 来消除不需要的，但这取决于您的用例。

如果你想从模式中隐藏一些东西，可以使用下面的方法

@Schema(description = "Example POJO to demonstrate the hidden attribute")
class Example {
    ...
    @Schema(hidden = true)    // <--- Will be hidden from the Swagger UI completely 
    String exampleId;
    ...
}

希望对您有所帮助。发表评论以获得任何澄清。

【讨论】：

感谢您的回答，但我使用的是 Spring Data REST。您的解决方案适用于普通 Spring MVC 应用程序
感谢您的更新。我还没有使用过 Spring Data REST，所以没有意识到这一点。 :)
@Tags 工作并解决了-search-controller 的问题。另见github.com/springdoc/springdoc-openapi/issues/834

【解决方案2】：

我向 Swagger 推荐 Spring REST Docs。 Spring REST Docs 是测试驱动的，以确保您的 API 文档始终与您的 API 同步。 Andy's talk 解释了为什么 Spring REST Docs 比 Swagger 更适合 API 文档。

您可以找到offical simple guide 和更多samples。

我的Github project 使用它。您可以克隆存储库并查看生成的文档 HTML /sga-booking/index.html。相关的 Spring REST Docs 文件是

如果您觉得我的 Github 有用，请考虑给它一颗星。

【讨论】：