SpringBoot整合Swagger2 API文档

概述

前后端分离开发模式中，api 文档是最好的沟通方式。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。具有及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)，规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)，一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)，可测性 (直接在接口文档上进行测试，以方便理解业务) 的特点。

配置Swagger2

1. 引入依赖

 
    <dependency>
        <groupId>io.springfoxgroupId>
        <artifactId>springfox-swagger2artifactId>
    dependency>
    <dependency>
        <groupId>io.springfoxgroupId>
        <artifactId>springfox-swagger-uiartifactId>
    dependency>
1
2
3
4
5
6
7
8
9

2. 写配置类,可以直接使用下面的配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //只显示api路径下的页面
                //.paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
    }

    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                .title("网站-API文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("xg", "http://xg.com", "2218877219@qq.com"))
                .build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

3. 测试，启动Spring Boot主程序，访问：http://localhost:端口号/swagger-ui.html，端口号是自己项目设置的端口号。
   
   
   Try it out–>Execute
   
   

4. 测试结果：
   

5. Swagger 使用的常用注解及其说明：

   @Api：用在类上，说明该类的作用。

   @ApiOperation：用在方法上,给API增加方法说明。

   @ApiParam，@ApiImplicitParams，@ApiImplicitParam：用在参数上,给API参数增加说明。

   @ApiModel 和 @ApiModelProperty主要是作用到实体类上，当接口中有一个方法的返回值为该对象时，就会在文档的model中显示该类的信息

   @ApiIgnore：用来排除不需要的接口信息

@Api(tags = "老师管理接口")
@RestController
@RequestMapping(value="/admin/teacher")
public class TeacherController {

    @Autowired
    private TeacherService teacherService;

    //删除老师
    @ApiOperation("逻辑删除老师")
    @DeleteMapping("{id}")
    public boolean removeById(@ApiParam(name = "id", value = "老师ID", required = true) @PathVariable String id){
        return teacherService.removeById(id);
    }

    //查询所有老师列表
    @ApiOperation("所有老师列表")
    @GetMapping("findAll")
    public List<Teacher> findAll(){
        List<Teacher> list = teacherService.list();
        return list;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

6. 补充说明：
   如果项目中整合了Security，需要在其配置文件中将swagger的访问放行。

@Override

public void configure(WebSecurity web) throws Exception {
	web.ignoring()
	.antMatchers("/swagger-ui.html")
	.antMatchers("/v2/**")
	.antMatchers("/swagger-resources/**");
}
1
2
3
4
5
6
7
8