在 DTO 上配置 Swagger javax 验证约束

validation java swagger

2022-09-01 19:34:02

我使用的是 Swagger （1.5.8）。我希望我的定义能够检测 DTO 上的 JSR-303 注释，以便我可以记录 API 的验证约束。swagger.jsonjavax.validation

我希望注释（如此示例）将显示有关最小值（44）的内容，但事实并非如此。@Min

@POST
@ApiOperation(value = "post", httpMethod = "POST")
public Response post(
        @QueryParam("id") @NotNull @Min(44) Integer id) {...}

结果是：swagger.json

"/foo": {
  "post": {
    "operationId": "post",
    ...
    "parameters": [
      {
        "in": "body",
        "name": "id",
        "description": "id",
        "required": false,
        "schema": {
          "type": "integer",
          "format": "int32"
        }
      }

Swagger已经关闭了对此功能的拉取请求，但我不清楚在Swagger定义中在哪里/如何能够使用它。

我希望能够做这样的事情：

FooController

@POST
public void postFoo(@Valid @RequestBody FooDTO fooDto) {...}

FooDTO

public class FooDTO {
    @NotNull
    @Size(min = 1, max = 100)
    private Integer myInt;
}

Desired/Expected swagger.json Output：

"FooDTO": {
  "type": "object",
  "required": [
    "myInt"
  ],
  "properties": {
    "myInt": {
      "type": "number",
      "format": "integer",
      "minimum": "1",
      "maximum": "100",
 ...

配置 Swagger 模块/插件以启用 ModelResolver 和 BeanValidator 等功能的首选方法是什么，以便它们检查我的 DTO 上的注释？

答案 1

截至目前，Swagger-Core版本1.5.19完全支持此功能：

DTO 对象类似于以下内容：

public class SampleDTO {

    @Min(value = 5)
    @Max(value = 10)
    @NotNull
    private Integer integer;

    @NotNull
    private String string;

    //...

}

将生成类似于以下内容的 swagger.json：

...

 "definitions" : {
    "SampleDTO" : {
      "type" : "object",
      "required" : [ "integer", "string" ],
      "properties" : {
        "integer" : {
          "type" : "integer",
          "format" : "int32",
          "minimum" : 5,
          "maximum" : 10
        },
        "string" : {
          "type" : "string"
        },

...

答案 2

我浏览了文档。从我的角度来看，对于swagger 1.x，您必须另外使用验证，就像在这个测试用例示例中一样：@QueryParam@ApiParam

@GET
@Path("/swagger-and-303")
@ApiOperation(value = "Get",
        httpMethod = "GET")
public Response getTestSwaggerAnd303(
        @ApiParam(value = "sample param data", required = false, allowableValues = "range[7, infinity]")
        @QueryParam("id") @NotNull @Min(5) Integer id) throws WebApplicationException {...`

此外，您可以尝试在特定情况下使用@ApiImplicitParam。