0

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

  1. 春狐：
  • 我无法更改存储库的标签名称，只能更改描述
  • 不支持预测
  • 尚不支持openAPI3（这其实不是什么大问题）
  1. Springdoc ( https://springdoc.org/ )
  • 我无法更改标签名称和描述（@Tag 不适用于 repos）
  • 不支持预测
  • 同一个仓库有 3 个标签，例如 books-entity-controller、books-search-controller（带有父类的方法）和 books-property-reference-controller（带有不必要的 /{id}/{property} url 列表）

有更好的办法吗？我喜欢 spring fox 不提供多个标签，而且自动生成的标签名称更好，例如 Books Entity 而不是 books-entity-controller。但最好是定制它或找到更好的替代方案。

4

2 回答 2

1

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

您可以找到官方的简单指南和更多示例。

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

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

于 2020-07-18T05:03:32.720 回答
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;
    ...
}

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

于 2020-07-21T11:25:04.703 回答