java - 使用 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 的存储库上打开一个问题。