当操作未使用 @ApiOperation 注释时，Swagger 忽略 JAX-RS @Produces

Question

我目前正在将 Swagger（版本 1.5.7 中的 swagger-jaxrs 工件）集成到我们现有的 JAX-RS REST 应用程序中。添加 Swagger 后，我将 @Api 注释添加到我们的接口类中，并且已经得到了一个看起来不错的文档。

不幸的是，在我使用 @ApiOperation 注释这些方法之前，Swagger 不会尊重我的 API 方法上的 @Produces 注释：

不将 text/plain 作为返回的媒体类型列出：

@GET
@Path("/overallStatus")
@Produces(MediaType.TEXT_PLAIN)
public String getOverallStatus() {
}

是否列出：

@GET
@Path("/overallStatus")
@Produces(MediaType.TEXT_PLAIN)
@ApiOperation(value = "Get the overall system status")
public String getOverallStatus() {
}

有没有办法在 Swagger 输出中包含媒体类型而不向所有媒体类型添加 @ApiOperation？由于所需的信息已经存在，我不明白为什么需要它。

Answer 1

您必须将 @ApiOperation 添加到您的 JAX-RS 端点，因为根据 Swagger Wiki 页面，没有 @ApiOperation 注释的方法将被忽略：

只有使用 @ApiOperation 注释的方法才会被扫描并添加 Swagger 定义。

您可以在这里找到更多信息：https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#apioperation