弹簧数据静止的Swagger 2或3

Question

我有一个使用spring数据rest的spring引导应用程序。我在使用swagger提供一个阅读良好的API文档时遇到了问题。我试过springfox和springdoc，但每个都有自己的问题

1. 春季狐狸：

• 我不能更改存储库的标记名，只能更改描述
• 不支持预测
• 目前还不支持openAPI3(这实际上不是什么大问题(

2. Springdoc(https://springdoc.org/)

• 我既不能更改标签名称也不能更改描述(@tag对repos无效(
• 不支持预测
• 同一个repo获得3个标签，例如books实体控制器、books搜索控制器(具有父类的方法(和books属性引用控制器(具有不必要的/｛id｝/｛property｝url列表(

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

Answer 1

我建议在Swagger上使用Spring REST文档。Spring REST文档是测试驱动的，以确保您的API文档始终与API同步。Andy的演讲更多地解释了为什么SpringRESTDocs比Swagger更适合API文档。

你可以找到官方的简单指南和更多的样品。

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

• FltApiDocumentation.java
• flts.adoc
• 预订ApiDocumentation.java
• booking.adoc

如果你觉得我的Github有用，可以考虑给它一颗星。

Answer 2

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;
...
}

希望能有所帮助。删除评论以进行任何澄清。