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

Question

我最近将一个项目从Swagger API 1.2升级到2.0(或者用Swagger核心术语,从1.3升级到1.5).由于他们出色的移民指南,我设法在很短的时间内完成了这项工作,几乎没有任何障碍.唯一困扰我的是缺乏对@Api注释description价值的支持.端点被精心记录 - 包括顶级API端点 - 但它们的描述不再在UI中显示:

请注意,缺少某些东西？

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

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

Answer 1

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

1. API端点(通常具有@Api注释)按标记分组,而不是按资源分组.例如,这可以使操作列在多个类别下.标签可以(但不一定)从注释的value属性派生@Api- 通常以斜杠开头.这使得分组,因此UI,迁移时的行为几乎是相同的,但也引起了我不认识的混乱description属性将被忽略- 东西一定要读的,对吧？

2. 标签是Swagger规范中的一等公民(见此处).它们是可扩展的,可以有描述,如本评论中所述.

3. 可以通过以编程方式将注释应用于Swagger可发现的任何资源来添加标记或增强现有标记.只需选择一个资源并在那里列出所需的描述 - 但一定要将它们放在一个地方.幸运的是,我碰巧有一个抽象类所有的资源都延伸了.因此,根据具体情况,我可以在最自然的地方写下描述:@Tag

   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之后,可以展示旧的描述,就像上面提到的评论一样.成就解锁.

要真正帮你搞定,一个现在可以删除@Api的description,从你的资源属性,作为描述从推断@Tag规格.