- 首先引入maven依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
- 基本配置：
@Configuration
@EnableSwagger2
public class SpringFoxConfig {
@Bean
public Docket apiDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
. @EnableSwagger2启用了SpringFox对于Swagger 2的支持
. DocumentationType.SWAGGER_2 告诉Docket这里使用的Swagger的版本号是2
. select()创建了一个builder
. apis()定义了需要被swagger显示的类（controller、model class）
. paths()定义了路径
那么，你应该知道下面这两个是干什么的咯：
RequestHandlerSelectors.basePackage("com.vojtechruzicka")
PathSelectors.ant("/v2/**")
访问路径，看一波：http://localhost:8080/v2/api-docs
image.png
- 添加ui：
首先引入依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
然后访问swagger ui地址：http://localhost:8080/swagger-ui.html
image.png
- 添加app信息
@Bean
public Docket apiDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.apiInfo(getApiInfo());
}
private ApiInfo getApiInfo() {
return new ApiInfo(
"TITLE",
"DESCIPRION",
"VERSION",
"TERMS OF SERVICE URL",
new Contact("NAME","URL","EMAIL"),
"LICENSE",
"LICENSE URL",
Collections.emptyList()
);
}
- 使用JSR-303注解
添加maven依赖：
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-validator</artifactId>
<version>5.3.6.Final</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-bean-validators</artifactId>
<version>2.9.2</version>
</dependency>
添加如下配置：
@Configuration
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
public class SpringFoxConfig {
...
}
然后就可以了
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, ...
}
image.png
- 向model类中添加Swagger注解
首先添加如下maven依赖：
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.9</version>
</dependency>
然后开始配置一波：
@ApiModel(description = "Class representing a person tracked by the application.")
public class Person {
@ApiModelProperty(notes = "Unique identifier of the person. No two persons can have the same id.", example = "1", required = true, position = 0)
private int id;
@ApiModelProperty(notes = "First name of the person.", example = "John", required = true, position = 1)
private String firstName;
@ApiModelProperty(notes = "Last name of the person.", example = "Doe", required = true, position = 2)
private String lastName;
@ApiModelProperty(notes = "Age of the person. Non-negative integer", example = "42", position = 3)
private int age;
// … Constructor, getters, setters, ...
}
- 向controller添加Swagger注解
. @Api注解用于描述整个controller
. @ApiOperation注解用户描述方法
. @ApiParam注解用户描述方法参数
@RestController
@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();
}
@RequestMapping(method = RequestMethod.GET, path = "/{id}", produces = "application/json")
@ApiOperation("Returns a specific person by their identifier. 404 if does not exist.")
public Person getPersonById(@ApiParam("Id of the person to be obtained. Cannot be empty.")
@PathVariable int id) {
return personService.getPersonById(id);
}
@RequestMapping(method = RequestMethod.DELETE, path = "/{id}")
@ApiOperation("Deletes a person from the system. 404 if the person's identifier is not found.")
public void deletePerson(@ApiParam("Id of the person to be deleted. Cannot be empty.")
@PathVariable int id) {
personService.deletePerson(id);
}
@RequestMapping(method = RequestMethod.POST, produces = "application/json")
@ApiOperation("Creates a new person.")
public Person createPerson(@ApiParam("Person information for a new person to be created.")
@RequestBody Person person) {
return personService.createPerson(person);
}
@Autowired
public void setPersonService(PersonService personService) {
this.personService = personService;
}
}
然后就这样了：
image.png
- 从配置文件中加载描述
步骤：
（1） 创建一个配置文件，比如swagger.properties
（2） 在配置文件中配置描述（跟正常的配置文件一样）
（3） 在注解中用placeholder ${persion.id}
（4） 在swagger配置类上添加引入配置文件 @PropertySource("classpath:swagger.properties")
@Configuration
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
@PropertySource("classpath:swagger.properties")
public class SpringFoxConfig {
...
}
