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

rest java swagger

2022-09-02 21:39:42

上下文

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

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

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

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

问题

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

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

答案 1

如果你正在使用弹簧项目，并且你正在使用弹簧狐狸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配置类之上导入BeanValidatorPlugins配置文件：

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

如果您没有用于swagger的配置类，请将其放在控制器上方

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

答案 2

使用 Swagger 注释，您可以使用和：@ApiModelPropertydataTypeallowableValuesrange

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

Swagger UI 上的结果：

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

allowableValues="range[5, 100]"