SpringBoot系列（五）SpringBoot 集成 Swagger2 生成接口文档

程序员最头疼的事是什么呢？我想一定是写接口文档，尤其是一大堆参数的那种。那么我们有没有办法改变这种情况呢？答案是肯定的。因此我们的主角 Swagger 登场了。

引入Swagger依赖包

创建springboot web 项目，引入以下依赖

		
            io.springfox
            springfox-swagger-ui
            2.9.2
        

        
            io.springfox
            springfox-swagger2
            2.9.2
        

创建 Swagger 配置类并开启注解

这里有两点要注意的地方：

1. 一定要开启 @EnableSwagger2 注解
2. 配置正确的扫描路径

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

/**
 1. Created by pengq on 2019/9/3 9:20.
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //swagger 的扫描路径，这里指的是生成该路径下所以类的文档
                .apis(RequestHandlerSelectors.basePackage("pengq.springboot.mybatisplus.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot2 集成 Swagger")
                .description("swagger 学习总结")
                .contact(new Contact("pengq","","[email protected]"))
                .version("1.0")
                .build();
    }
}

在Controller 中配置 Swagger 注解

1. 首先需要在我们的controller类上打上 @Api 注解
2. 编写方法体上的描述信息，这里列举了几种常见的Controller编写方式，如果不全面欢迎大家补充。

示例1：无参数的接口

    @ApiOperation("查询所有用户")
    @ApiResponses({
            @ApiResponse(code = 200, message = "操作成功", response = Users.class),
            @ApiResponse(code = 500, message = "服务器内部异常")
    })
    @GetMapping(value = "/v1/users/", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public Object getAllUser() {
        return userService.listUser();
    }

示例2：有参数 用 @RequestBody 接收

    @ApiOperation("用户注册")
    @PostMapping(value = "/v1/users/register", consumes = MediaType.APPLICATION_JSON_UTF8_VALUE, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public Object register(@RequestBody Users users) {
        return userService.register(users);
    }

示例3：参数 用 @PathVariable 接收

    @ApiOperation("查询用户详情")
    @ApiImplicitParam(paramType = "path", name = "id")
    @GetMapping(value = "/v1/users/{id}", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public Object getUserInfo(@PathVariable("id") Integer id) {
        return userService.getUserById(id);
    }

示例4：多参数 用 @RequestParam 接收

	@ApiOperation("用户登录")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "username", value = "登录名",required = true),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "password", value = "登录密码",required = true)
    })
    @PostMapping(value = "/v1/users/login", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public Object login(@RequestParam(name = "username") String username,
                        @RequestParam(name = "password") String password) {
        return userService.login(username, password);
    }

示例5：参数 用 @RequestHeader 接收

	@ApiOperation("header 测试")
    @ApiImplicitParam(paramType = "header", dataType = "String", name = "token", value = "token")
    @PostMapping(value = "/v1/users/check", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public Object check(@RequestHeader("token") String token) {
        return token;
    }

好，到此我们的swagger配置已经完成了，启动我们的项目，感受一下他的强大吧
访问url: http://localhost:8080/swagger-ui.html
这个就是swagger的web界面，该url的访问规则为 http://ip:端口号/swagger-ui.html

Swagger 常用注解总结

注解	属性	值	使用方式	描述
@Api			@Api(value = "xx", tags = "xx",hidden = false)
	value	字符串		url的路径值
	tags	字符串		对controller的描述，如果设置这个值、value的值会被覆盖
	hidden	boolean		如果设置为true，该文档将会被隐藏
@ApiOperation			@ApiOperation("xxx")
	value	字符串		用在方法头上，作为方法的描述
@ApiImplicitParams			@ApiImplicitParams({@ApiImplicitParam(xxx)})
	数组	@ApiImplicitParam		用在方法头上，作为方法参数的描述
@ApiImplicitParam			@ApiImplicitParam(paramType = "query", dataType = "String", name = "xxx", value = "xxx")
	name	字符串		与参数名对应
	value	字符串		参数名的描述
	required	boolean		true/false 是否必须
	dataType	字符串		参数类型
	paramType	字符串		参数请求方式：query/path/header/body
		query		对应@RequestParam传递
		path		对应@PathVariable传递
		header		对应@RequestHeader传递
		body		不推荐使用，与 @RequestBody标签一起会导致错误
	defaultValue	字符串		参数不传递时的默认值
@ApiResponses			@ApiResponses({@ApiResponse()})
	数组	@ApiResponse		用在方法头上，作为方法返回值的描述
@ApiResponse			@ApiResponse(code = 200, message = "操作成功", response = Users.class)
	code	整形		返回值编码
	message	字符串		返回值的描述信息
	response	Class		返回值类型

---

Swagger集成项目地址：Swagger集成项目地址