Question

上下文

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

除此之外，我们还提议使用注释提供资源文档。

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

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

问题

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

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

Answer 1

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

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）并且您需要在svagger配置类之上导入BeanValidatorPluginsConfiguration配置文件：

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

如果您没有招摇的配置类，则将其放在您的控制器上方

 @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批注的数据，在草率的文档中看起来会更好：

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

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

Answer 2

使用@ApiModelProperty Swagger批注，可以使用dataType，allowableValues和range：

@ApiModelProperty(value = "Nome da lista", required = false, 
    dataType="java.lang.String", 
    allowableValues="range[-infinity, 100]")
String getNome();

Swagger UI上的结果：

-infinity用于隐藏最小值。如果要设置最小值，只需填写数字：

allowableValues="range[5, 100]"

Answer 3

是的，请参阅swagger规范的this section。您可以为您的媒体资源指定maxLength或minLength。以下是YAML中的一个示例：

definitions:
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
        maxLength: 20

这将由swagger-ui显示如下：

有没有办法表明字符串模型属性在Swagger中具有最大长度？

上下文

问题

3 个答案: