我最近将一个项目从 Swagger API 1.2 升级到 2.0（或者用 Swagger 核心术语来说，从 1.3 升级到 1.5）。因为他们的优秀迁移指南，我设法在很短的时间内做到这一点，而且几乎没有遇到任何困难。唯一困扰我的是缺乏对@Api注释的description价值。端点都经过精心记录 - 直至并包括顶级 API 端点 - 但它们的描述不再显示在 UI 中：
Notice that something's missing?
一些研究（意思是阅读源代码）得出了同样的结果descriptions现在已经过时了，为爱好者腾出了空间@Tag注释。但我找不到有关如何应用它们的信息，因此描述仍位于每个端点类中。
仅使用 Dropwizard，有没有办法以编程方式在 Swagger 1.5 中实现这一点？
我通过理解几个概念最终解决了这个问题：
API 端点（通常具有@Api注解）按标签分组，而不是按资源分组。例如，这可以使一项操作列在多个类别下。标签可以（但不是必须）源自value的属性@Api注释——通常以斜杠开头的注释。这使得分组以及 UI 在迁移时的行为几乎相同，但也让我感到困惑，因为没有意识到description属性被忽略 –某物一定正在读那个，对吧？
在 Swagger 的规范中，标签是一等公民（see here）。它们是可扩展的并且可以有描述，如中所述这条评论.
可以添加标签或增强现有的通过以编程方式应用@Tag注解 to anySwagger 可发现的资源。只需选择一个资源并在那里列出所需的描述 - 但请务必将它们放在一个地方。对我来说幸运的是，我碰巧有一个所有资源都扩展的抽象类。因此，考虑到当时的情况，我可以在最自然的地方写下描述：
import io.swagger.annotations.Contact;
import io.swagger.annotations.Info;
import io.swagger.annotations.SwaggerDefinition;
import io.swagger.annotations.Tag;
and then
@SwaggerDefinition(
info = @Info(
title = "My API",
version = "0.1",
contact = @Contact(name = "Me", email = "[email protected]")
),
tags = {
@Tag(
name = "pets", description = "Manage pets"
), @Tag(
name = "search", description= "Search pets"
), ...
}
)
public class BaseResource {
...
}
瞧！编译并启动 UI 后即可显示旧的新描述，就像前面提到的那样comment。成就已解锁。
为了真正达成协议，现在可以删除@Api's description来自您的资源的属性，因为描述是从@Tag规格。