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

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

请注意，缺少某些东西？

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

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

Answer 1

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

1. API端点（通常具有@Api注释） 按标记分组，而不是按资源分组 。 例如，这可以使操作列在多个类别下。 标签可以（但不一定）从@Api注释的value属性派生 – 通常以斜杠开头。 这使得分组和UI在迁移时的行为几乎相同，但也让我感到困惑，因为没有意识到description属性被忽略了 – 必须要阅读它，对吧？

2. 标签是Swagger规范中的一等公民（ 见这里 ）。 它们是可扩展的，可以有描述，如本评论中所述 。

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

    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 = "[e-mail]") ), tags = { @Tag( name = "pets", description = "Manage pets" ), @Tag( name = "search", description= "Search pets" ), ... } ) public class BaseResource { ... } 

瞧！ 在编译和启动UI之后，可以展示旧的描述，就像上面提到的评论一样 。 成就解锁。

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