SpringBoot项目集成swagger2

什么是swagger2

编写和维护接口文档是每个程序员的职责，根据 Swagger2 可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。常用注解swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

swagger2常用的注解说明

注解	属性	值	备注
@Api	value	字符串	可用在class头上,class描述
	description	字符串
			@Api(value = “xxx”, description = “xxx”)
@ApiModel	value	字符串	可用在实体类上，不可重复
	description	字符串	可用在实体类上，实体类描述
@ApiModelProperty	value	字符串	可用在实体类属性上，属性说明
@ApiOperation	value	字符串	可用在方法头上.参数的描述容器
	notes	字符串
			@ApiOperation(value = “xxx”, notes = “xxx”)
@ApiImplicitParam	name	字符串 与参数命名对应	可用在@ApiImplicitParams里
	value	字符串	参数中文描述
	required	布尔值	true/false
	dataType	字符串	参数类型
	paramType	字符串	参数请求方式:query/path
			query:对应@RequestParam?传递
			path: 对应@PathVariable{}path传递
	defaultValue	字符串	在api测试中默认值
			用例参见项目中的设置
@ApiResponses	{}	@ApiResponse数组	可用在方法头上.参数的描述容器
			@ApiResponses({@ApiResponse1,@ApiResponse2,…})
@ApiResponse	code	整形	可用在@ApiResponses里
	message	字符串	错误描述
			@ApiResponse(code = 200, message = “Successful”)

快速入门

引入依赖

<!-- swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

SwaggerConfig 配置

package io.yjff.demo.config;

import com.google.common.base.Predicates;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * description: Swagger2 配置类
 * @Configuration 让 Spring 容器加载该配置类
 * date: 2020/6/14 14:22
 * author: ***
 * version: 1.0
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).pathMapping("/").
                select() // 选择那些路径和api会生成document
                .apis(RequestHandlerSelectors.any())// 对所有api进行监控
                // 不显示错误的接口地址
                .paths(Predicates.not(PathSelectors.regex("/error.*")))// 错误路径不监控
                .paths(PathSelectors.regex("/.*"))// 对根下所有路径进行监控
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("产品接口文档")
                // .contact(new Contact("***", "", "******@qq.com"))
                .description("demo生成的接口文档")
                // .termsOfServiceUrl("NO terms of service")
                // .license("The Apache License, Version 2.0")
                // .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
//                 .version("v1.0")
                .build();
    }

}

controller注解

@Api

@Slf4j
@RestController
@RequestMapping("user")
@Api(tags = "用户管理")
public class UserController {
}

@ApiOperation

@ApiOperation(value = "用户列表", notes = "用户列表查询")
@GetMapping("list")
public List<UserEntity> list() {
    return Collections.emptyList();
}

@ApiParam

@ApiOperation(value = "用户列表1", notes = "用户列表查询")
@GetMapping("list1")
public List<UserEntity> list1(@ApiParam(name = "userName", value = "用户名", required = true) @RequestParam("userName") String userName,
                              @ApiParam(name = "age", value = "年龄") @RequestParam(value = "age", required = false) Integer age) {
    log.info("username:{};age:{}", userName, age);
    return Collections.emptyList();
}

@ApiImplicitParams & @ApiImplicitParam

@ApiOperation(value = "用户列表2", notes = "用户列表查询")
@GetMapping("list2")
@ApiImplicitParams({
        @ApiImplicitParam(name = "userName", value = "用户名", required = true, paramType = "query", dataType = "string"),
        @ApiImplicitParam(name = "age", value = "年龄", paramType = "query", dataType = "Integer")
})
public List<UserEntity> list2(@RequestParam("userName") String userName,
                             @RequestParam(value = "age", required = false) Integer age) {
    return Collections.emptyList();
}

@ApiIgnore

使用该注解忽略这个API，用于类或者方法上

@ApiOperation(value = "用户列表3", notes = "用户列表查询")
@GetMapping("list3")
@ApiImplicitParams({
        @ApiImplicitParam(name = "userName", value = "用户名", required = true, paramType = "query", dataType = "string"),
        @ApiImplicitParam(name = "age", value = "年龄", paramType = "query", dataType = "Integer")
})
public List<UserEntity> list3(@ApiIgnore @RequestParam Map<String, Object> param) {
    log.info("params:{}", param);
    return Collections.emptyList();
}

@ApiResponses & @ApiResponse

@ApiOperation(value = "用户列表2", notes = "用户列表查询")
@GetMapping("list2")
 @ApiImplicitParams({
         @ApiImplicitParam(name = "userName", value = "用户名", required = true, paramType = "query", dataType = "string"),
         @ApiImplicitParam(name = "age", value = "年龄", paramType = "query", dataType = "Integer")
 })
 @ApiResponses(value = {
         @ApiResponse(code = 200, message = "Success"),
         @ApiResponse(code = 400, message = "参数问题"),
         @ApiResponse(code = 401, message = "未登录"),
         @ApiResponse(code = 404, message = "找不到路径"),
         @ApiResponse(code = 500, message = "服务器内部异常")}
 )
 public List<UserEntity> list2(@RequestParam("userName") String userName,
                              @RequestParam(value = "age", required = false) Integer age) {
     return Collections.emptyList();
 }

实体注解

@ApiModel & @ApiModelProperty

package io.yjff.demo.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @description: user实体
 * @author: ***
 * @time: 2020/6/9 17:01
 */
@Data
@ApiModel(value = "UserEntity", description = "用户实体")
public class UserEntity {

    @ApiModelProperty("ID")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("年龄")
    private Integer age;
    
}

接口测试

启动swagger项目，访问项目ip+/端口+/工程路径+/swagger-ui.html访问swagger接口文档页面。打开对应的方法，输入接口参数点击按钮try it out即可调用对应的接口。