Swagger 1.5 不显示我的 1.2 的 @Api 描述？

Question

我最近将一个项目从 Swagger API 1.2 升级到 2.0（或者，用 Swagger 核心术语来说，从 1.3 升级到 1.5）。由于他们的优秀migration guide，我在很短的时间内几乎顺利地做到了。唯一困扰我的是缺少对 @Api 注释的 description 值的支持。端点被精心记录 - 直到并包括顶级 API 端点 - 但它们的描述不再显示在 UI:

注意到少了什么吗？

一些研究（意思是阅读源代码）表明相同的 description 现在已经过时，为更高级的 @Tag 注释腾出了空间。但是我找不到关于如何应用它们的信息，所以描述仍然在每个端点 class.

仅使用 Dropwizard，有没有办法以编程方式在 Swagger 1.5 中实现这一点？

Answer 1

我通过理解几个概念最终解决了这个问题：

API 端点（通常有 @Api 注释）are grouped by Tag, not by resource。例如，这可以使一项操作列在多个类别下。标签可以但不是必须从 @Api 注释的 value 属性派生——通常以斜线开头的注释。这使得分组，因此 UI，在迁移时表现几乎相同，但也让我感到困惑，因为没有意识到 description 属性被忽略了 – something 一定是在读那个吧？
标签是 first-class Swagger 规范中的公民（see here). They are extensible and can have descriptions, as mentioned in this comment。

可以将标签或 enhance existing ones by programmatically apply the @Tag annotation 添加到任何 Swagger 可发现的资源。只需选择一个资源并在其中列出所需的描述——但请务必将它们放在一个地方。幸运的是，我碰巧有一个抽象的 class 所有资源扩展。所以我可以把描述写在最自然的地方，考虑到情况：

import io.swagger.annotations.Contact;
import io.swagger.annotations.Info;
import io.swagger.annotations.SwaggerDefinition;
import io.swagger.annotations.Tag;

然后

@SwaggerDefinition(
  info = @Info(
    title = "My API",
    version = "0.1",
    contact = @Contact(name = "Me", email = "me@myself.com")
  ),
  tags = {
   @Tag(
     name = "pets", description = "Manage pets"
   ), @Tag(
     name = "search", description= "Search pets"
   ), ...
  }
)
public class BaseResource {
...
}

瞧！ old-new 描述可以在编译并启动 UI 后显示，就像在上述 comment 中看到的一样。成就解锁。

为了真正达成交易，现在可以从您的资源中删除 @Api 的 description 属性，因为描述是从 @Tag 规范中推断出来的。

Swagger 1.5 不显示我的 1.2 的 @Api 描述？

Swagger 1.5 Doesn't Display My 1.2's @Api Description?

java

dropwizard

swagger-ui

swagger-2.0