Spring Boot2配置Swagger2生成API接口文档

一、Swagger2介绍

前后端分离开发模式中，api文档是最好的沟通方式。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

• 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
  
• 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
  
• 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
  
• 可测性 (直接在接口文档上进行测试，以方便理解业务)
  

二、配置Swagger2

1、引入相关依赖

1. <dependency>
2.         <groupId>io.springfox</groupId>
3.         <artifactId>springfox-swagger2</artifactId>
4.         <version>2.7.0</version>
5. </dependency>
7. <dependency>
8.         <groupId>io.springfox</groupId>
9.         <artifactId>springfox-swagger-ui</artifactId>
10.         <version>2.7.0</version>
11. </dependency>

复制代码

2、创建swagger的配置类

1. @Configuration
2. @EnableSwagger2
3. public class SwaggerConfig {
5.     @Bean
6.     public Docket webApiConfig(){
7.         return new Docket(DocumentationType.SWAGGER_2)
8.                 .groupName("webApi")
9.                 .apiInfo(webApiInfo())
10.                 .select()
11.                 .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
12.                 .paths(Predicates.not(PathSelectors.regex("/error.*")))
13.                 .build();
15.     }
17.     private ApiInfo webApiInfo(){
19.         return new ApiInfoBuilder()
20.                 .title("XX平台API文档")
21.                 .description("本文档描述了xxx接口定义")
22.                 .version("1.0")
23.                 // 创建人
24.                 .contact(new Contact("Jade", "http://jade.com", "55317362@qq.com"))
25.                 .build();
26.     }
27. }

复制代码

3、在启动类上添加注解扫描swagger的配置类，进行测试

要能扫描到swagger的配置类SwaggerConfig

1. @SpringBootApplication
2. // 要能扫描到swagger的配置类SwaggerConfig
3. @ComponentScan(basePackages = {"com.jade"})
4. public class Application {
5.     public static void main(String[] args) {
6.         SpringApplication.run(Application.class, args);
7.     }
8. }

复制代码

4、API模型

可以添加一些自定义设置，例如：
定义样例数据

1. @ApiModelProperty(value = "创建时间", example = "2019-01-01 8:00:00")
2. @TableField(fill = FieldFill.INSERT)
3. private Date gmtCreate;
5. @ApiModelProperty(value = "更新时间", example = "2019-01-01 8:00:00")
6. @TableField(fill = FieldFill.INSERT_UPDATE)
7. private Date gmtModified;

复制代码

5、定义接口说明和参数说明

定义在类上：@Api
定义在方法上：@ApiOperation
定义在参数上：@ApiParam

1. @Api(description="讲师管理")
2. @RestController
3. @RequestMapping("/admin/edu/teacher")
4. public class TeacherAdminController {
6.     @Autowired
7.     private TeacherService teacherService;
9.     @ApiOperation(value = "所有讲师列表")
10.     @GetMapping
11.     public List<Teacher> list(){
12.         return teacherService.list(null);
13.     }
15.     @ApiOperation(value = "根据ID删除讲师")
16.     @DeleteMapping("{id}")
17.     public boolean removeById(
18.             @ApiParam(name = "id", value = "讲师ID", required = true)
19.             @PathVariable String id){
20.         return teacherService.removeById(id);
21.     }
22. }

复制代码

6、测试，查看效果

访问http://localhost:8080/swagger-ui.html 即可


免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！