java - 有没有办法指示字符串模型属性在 Swagger 中具有最大长度？

Question

上下文

我们有一个提供多个 REST 网络服务的网络应用程序。

除此之外，我们还 Swagger 使用注解为资源提供文档。

其中一些资源将输入中的复杂对象作为正文参数。此对象的类使用 @ApiModel 注释。

在某些情况下，我们使用来自 Bean Validations 的 @Length 注释来限制某些字符串属性的长度。

问题

我们希望看到这些限制在 swagger 生成的文档中可见。有办法做到这一点吗？

P.S.:@Length 注释的自动解释会很好，但不是强制性的。任何其他方式也行。

Answer 1

如果你正在使用 spring 项目并且你正在使用 spring fox swagger api，你可以做得很好。考虑一个 bean -

public class Person {
    @NotNull
    private int id;

    @NotBlank
    @Size(min = 1, max = 20)
    private String firstName;

    @NotBlank
    @Pattern(regexp ="[SOME REGULAR EXPRESSION]")
    private String lastName;

    @Min(0)
    @Max(100)
    private int age;

    //... Constructor, getters, setters, ...
}

使用 Maven 依赖 -

//MAVEN
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
//MAVEN
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-bean-validators</artifactId>
   <version>2.9.2</version>
</dependency>

这会发挥你的魔力 - @Import(BeanValidatorPluginsConfiguration.class)您需要在 swagger 配置类之上导入 BeanValidatorPluginsConfiguration 配置文件:

  @Configuration
    @EnableSwagger2
    @Import(BeanValidatorPluginsConfiguration.class)
    public class SpringFoxConfig {
      ...
    }

如果你没有 swagger 的配置类，那么把它放在你的 Controller 之上

 @RestController
     @EnableSwagger2
        @Import(BeanValidatorPluginsConfiguration.class)
    @RequestMapping("/v2/persons/")
    @Api(description = "Set of endpoints for Creating, Retrieving, Updating and Deleting of Persons.")
    public class PersonController {

        private PersonService personService;

        @RequestMapping(method = RequestMethod.GET, produces = "application/json")
        @ApiOperation("Returns list of all Persons in the system.")
        public List getAllPersons() {
            return personService.getAllPersons();
        }

使用来自 JSR-303 注释的数据，它在 swagger 文档中看起来会好得多:

{
        age integer ($int32)
                    minimum: 100
                    maximum: 100
        firstName* string
                minimumLength: 100
                maxLength: 100
    }

JSR 303:Bean 验证允许您注释 Java 类的字段以声明约束和验证规则。您可以使用诸如 -- 不能为空、最小值、最大值、正则表达式匹配等规则来注释各个字段。这是一种已经被广泛使用的常见做法。好消息是 SpringFox 可以根据此类注释生成 Swagger 文档，因此您可以利用项目中已有的内容，而无需手动编写所有约束!这非常有用，因为您的 API 的使用者知道他们应该提供给您的 API 的值有哪些限制以及期望值是什么。如果不包含此类注释，为我们的人员模型生成的文档看起来相当简单，除了字段名称及其数据类型外什么都没有。