使用 Swagger-UI @ApiParam 注释 @FormParam 字段

Question

我已经构建了一个 RestEasy API 并将其与 Swagger UI 链接。我被要求完成的一项任务是，找到一种方法来减少方法签名中的查询参数并在某种“DTO”中处理它们。

我的原始实现类似于：

  @GET
  @ApiOperation(value = "echo test value", notes = "echo test notes")
  @ApiResponse(code = HttpServletResponse.SC_OK, message = "Response.status.OK")
  public Response echoTest(
    @ApiParam("id") @QueryParameter("id") final int id,
    @ApiParam("fName") @QueryParameter("fName") final String fName,
    @ApiParam("sName") @QueryParameter("sName") final String sName) {

    // handle request

  }

我已将查询参数处理提取到 DTO，尽管现在我不确定如何处理 Swagger-UI 方面的事情。我试图注释 DTO 中的字段，但正如我猜想的那样，这不起作用。我的当前解决方案没有正确的 swagger-ui 交互：

  @GET
  @ApiOperation(value = "echo test value", notes = "echo test notes")
  @ApiResponse(code = HttpServletResponse.SC_OK, message = "Response.status.OK")
  public Response echoTest(@ApiParam("form") @FormParam QueryDTO dto) {

    //Handle request

  }

QueryDTO.java：

public class QueryDTO {

  @ApiParam(name = "id", value = "user id") @QueryParam("id") private int id;
  @ApiParam(name = "fName", value = "user first name") @QueryParam("fName") private String fName;
  @ApiParam(name = "sName", value = "user surname") @QueryParam("sName) private String sName;

  // Getters,setters etc

}

SwaggerUI 是否支持此类功能？是否有适合我用例的替代方法？任何建议或帮助表示赞赏，谢谢。

Answer 1

这里的问题不是 Swagger-UI，而是 Swagger-Core。

Swagger-Core 不支持 RESTEasy 的 @Form 注解，只支持标准的 JAX-RS 注解。

在您提到它之前，我并不熟悉该注释，但它看起来与 JAX-RS 2.0 中引入的 @BeanParam 的行为方式相同。 RESTEasy 3.0 及更高版本应提供对它的支持。 Swagger-core 能够处理 @BeanParam 以生成正确的文档。

如果您仍然只想支持 @Form，则必须在 Swagger-Core 的存储库上打开一个问题。