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

Question

上下文

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

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

其中一些资源将输入中的复杂对象作为正文参数。该对象的 class 被注释为 @ApiModel.

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

问题

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

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

Answer 1

是的，请参阅 swagger 规范的 this section。您可以为属性指定 maxLength 或 minLength。这是 YAML 中的示例：

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

这将由 swagger-ui 显示如下：

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

如果你正在使用 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) 并且您需要在 swagger 配置之上导入 BeanValidatorPluginsConfiguration 配置文件 class:

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

如果你没有 swagger 的配置 class 然后把它放在你的控制器上面

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

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

Is there a way to indicate that a string model property has a maximum length in Swagger?

java

rest

swagger

上下文

问题

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

Is there a way to indicate that a string model property has a maximum length in Swagger?

java

rest

swagger

上下文

问题

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