Is there a way to indicate that a string model property has a maximum length in Swagger?
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.
Using the @ApiModelProperty
Swagger annotation, you can use dataType
, allowableValues
and range
:
@ApiModelProperty(value = "Nome da lista", required = false,
dataType="java.lang.String",
allowableValues="range[-infinity, 100]")
String getNome();
Result on Swagger UI:
The -infinity
is used to hide the minimum value. If you would like to set the min value, just fill with the number:
allowableValues="range[5, 100]"