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

Question

Context

We have a web application providing multiple REST webservice.

Along with this, we have swagger providing the documentation for the resources, using annotation.

Some of these resources take a complex object in input as a body param. The class of this object is annotated with @ApiModel.

In some cases, we limit the length of some string properties, using @Length annotation from Bean Validations.

Question

We want to see these restrictions to be visible in the documentation generated by swagger. Is there a way to do this?

P.S.: the automatic interpretation of the @Length annotation would be nice but is not mandatory. Any other way would work too.

Answer 1

You can do very nicely if you are using spring project and you are using spring fox swagger api. Consider a 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, ...
}

Use Maven dependency -

//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>

This will do your magic - @Import(BeanValidatorPluginsConfiguration.class) And you need to import BeanValidatorPluginsConfiguration configuration file on top of your swagger configuration class:

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

If you dont have a configuration class for swagger then put it above your 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();
        }

With data from JSR-303 annotations, it will look much better in swagger documentation:

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

JSR 303: Bean Validation allows you to annotate fields of your Java classes to declare constraints and validation rules. You can annotate individual fields with rules such as -- cannot be null, minimal value, maximal value, regular expression match and so on. This is a common practice which is already widely used. The good news is that SpringFox can generate Swagger documentation based on such annotations, so you can utilize what you already have in your project without writing all the constraints manually! It is very useful as consumers of your API know what are restrictions on the values they should provide to your API and what values to expect. Without the inclusion of such annotations, the generated documentation for our person model looks rather plain, nothing except for field names and their data type.