Swagger UI 显示 JAX-RS 资源的错误状态代码

Question

我有一个很简单的删除方法：

/**
 * Delete the question with the specified id
 *
 * @return a <code>204 NO CONTENT</code> on success or a <code>404 NOT FOUND</code> if there is no question available
 * @successResponse 204 The question was successfully deleted
 * @errorResponse 404 The question does not exist
 */
@DELETE
public Response delete(@PathParam("questionId") final Long questionId) {
    final Question question = findByQuestionId(questionId); // throws NotFoundException
    questionService.delete(question.getQuestionId());
    return Response.noContent().build();
}

如您所见，我使用 JavaDoc 标记来指定成功和错误响应代码。在该方法中，我创建了一个无内容响应（状态码为 204）。这是 swagger-doclet 生成的：

{
  "method" : "DELETE",
  "nickname" : "delete",
  "type" : "Response",
  "parameters" : [ {
    "type" : "integer",
    "format" : "int64",
    "paramType" : "path",
    "name" : "questionId",
    "required" : true
  } ],
  "summary" : "Delete the question with the specified id",
  "responseMessages" : [ {
    "code" : 204,
    "message" : "The question was successfully deleted"
  }, {
    "code" : 404,
    "message" : "The question does not exist"
  } ],
  "produces" : [ "application/json" ]
}

到目前为止，一切都很好：它使用我的 JavaDoc 标记以及成功和错误响应代码。此外，还有一种“响应”类型，似乎取自方法返回语句。现在，当我打开 Swagger UI 时，我得到了以下视图：

在顶部您可以看到“响应类（状态 200）”，其中“响应类”是正确的，但“状态 200”是错误的！在此方法中，我无处返回状态代码 200（OK）。我没有找到任何可行的解决方案来纠正此输出。

我用什么：

• Java 8
• Maven 3.3.9
• Dropwizard 0.9.2
• org.apache.maven.plugins.maven-javadoc-plugin 2.10.3
• com.tenxerconsulting.swagger-doclet 1.1.3

如果你想尝试一下，完整的项目在 GitHub 上：https://github.com/McPringle/moodini

获得正确的 Swagger API 文档真的很棒。任何帮助表示赞赏。

非常感谢！

Answer 1

这似乎是由 swagger-ui 自动呈现的。

您是否尝试使用嵌套 @ApiResponse 的 @ApiResponses ？

/**
 * Delete the question with the specified id
 *
 * @return a <code>204 NO CONTENT</code> on success or a <code>404 NOT FOUND</code> if there is no question available
 */
@ApiResponses(value = { 
      @ApiResponse(code = 204, message = "The question was successfully deleted"),
      @ApiResponse(code = 404, message = "The question does not exist")
})
@DELETE
public Response delete(@PathParam("questionId") final Long questionId) {
    final Question question = findByQuestionId(questionId); // throws NotFoundException
    questionService.delete(question.getQuestionId());
    return Response.noContent().build();
}

编辑：完整文档在这里： https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#apiresponses-apiresponse