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

Question

我最近将一个项目从 Swagger API 1.2 升级到 2.0（或者，用 Swagger 核心术语来说，从 1.3 升级到 1.5）。由于他们出色的migration guide，我设法在很短的时间内做到了这一点，而且几乎没有任何障碍。唯一困扰我的是缺乏对 @Api 注释的 description 值的支持。端点被精心记录——直到并包括顶级 API 端点——但它们的描述不再显示在 UI 中：

注意到缺少什么了吗？

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

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

Answer 1

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

1. API 端点（通常具有@Api 注释）are grouped by Tag, not by resource。例如，这可以使一个操作列在一个以上的类别下。标签可以（但不是必须）从@Api 注释的value 属性派生——通常以斜杠开头。这使得分组以及 UI 在迁移时的行为几乎相同，但也让我感到困惑，没有意识到 description 属性被忽略了 - something 一定是在读取它，对吗？

2. 标签是 Swagger 规范中的一等公民 (see here)。如this comment 中所述，它们是可扩展的并且可以有描述。

3. 可以通过以编程方式将@Tag annotation 应用于Swagger 可发现的任何 资源来添加标签或enhance existing ones。只需选择一个资源并在其中列出所需的描述——但请确保它们只放在一个地方。幸运的是，我碰巧有一个所有资源都扩展的抽象类。因此，考虑到情况，我可以在最自然的地方写描述：

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

瞧！新旧描述可以在编译并启动 UI 后展示，就像前面提到的comment 中看到的一样。成就解锁。

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