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注释腾出了空间。但我找不到有关如何应用它们的信息，因此描述仍然在每个端点类中。

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

Answer 1

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

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

2. 标签是Swagger规范中的一等公民（see here）。它们是可扩展的，可以有this comment中提到的描述。

3. 可以通过编程方式将enhance existing ones应用于Swagger可发现的任何资源，从而添加代码或@Tag annotation。只需选择一个资源并在那里列出所需的描述 - 但一定要将它们放在一个地方。幸运的是，我碰巧有一个抽象类所有的资源都延伸了。因此，考虑到具体情况，我可以在最自然的地方写下描述：

   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的{​​{1}}属性，因为说明是根据description规范推断的。