Swagger2介绍与使用

Swagger是什么？它能干什么？

Swagger 是一款目前世界最流行的API管理工具。但目前Swagger已经形成一个生态圈，能够管理API的整个生命周期，从设计、文档到测试与部署。

SpringBoot+Swagger2配置

官方提供了两个版本让项目去集成swagger：我们这里使用第一个版本：springfox-swagger2 (新版本)

1. 引入jar包依赖

<dependencies>
    ...

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
​
    <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
    </dependency>
</dependencies>

2.创建 Swagger2Configuration.java

该类放在springboot能扫描的目录下即可

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;
​
@Configuration  
@EnableSwagger2
public class Swagger2Configuration {
​
   //api接口包扫描路径
   public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.xxx";
​
   public static final String VERSION = "1.0.0";
​
   @Bean
   public Docket createRestApi() {
       return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE)) 
                   .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                   .build();
   }
​
   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
                   .title("xxx服务") //设置文档的标题
                   .description("xxx API 接口文档") // 设置文档的描述
                   .version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information
                   .termsOfServiceUrl("http://www.xxx.com") // 设置文档的License信息->1.3 License information
                   .build();
   }
}

如上代码所示，通过 @Configuration 注解，让 Spring 加载该配置类。再通过 @EnableSwagger2 注解来启用Swagger2。成员方法 createRestApi 函数创建 Docket 的Bean之后，apiInfo() 用来创建该 Api 的基本信息（这些基本信息会展现在文档页面中）。select() 函数返回一个 ApiSelectorBuilder实例用来控制哪些接口暴露给 Swagger 来展现，本例采用指定扫描的包路径来定义，Swagger 会扫描该包下所有 Controller 定义的 API，并产生文档内容（除了被 @ApiIgnore 指定的请求）。

3.类和方法上加注解

控制层添加@Api(tags = “黑白名单Controller”)
方法上添加 @ApiOperation(“黑名单列表”)

@RequestMapping("/web/its/blacklist/blackList")
@RestController
@Slf4j
@Api(tags = "黑白名单Controller")
public class BlackListController {
    @Autowired(required = false)
    @Qualifier("blackListService")
    private BlackListService blackListService;

	@ApiOperation("黑名单列表")
	@PostMapping("listBlackList")
	public WrapperResponse<PageResultData<BlackListDTO>> listBlackList(@RequestBody BlackListParamDTO param){
        WrapperResponse<PageResultData<BlackListDTO>> res;
        try{
            res = blackListService.listBlackList(param);
        }catch (Exception e){
            log.error("失败:"+e.getMessage());
            return WrapperResponse.error(230225,e.getMessage(),null);
        }
        return res;
    }

实体类中变量添加@ApiModelProperty("")注解

@Data
public class ApplyDTO extends BaseDTO implements Serializable {
    private static final long serialVersionUID = 2020041716453502165L;
    public static  final String KEY_ID="HSA:ITS:ITS_MATT_APPY_C:APPY_ID";
    
	/**
	* 受理时间
	*/
	@ApiModelProperty("受理时间")
	@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
	@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
	private Date acpTime;
	/**
	* 受理人
	*/
	@ApiModelProperty("受理人")
	private String acper;
	/**
	* 受理人姓名
	*/
	@ApiModelProperty("受理人姓名")
	private String acperName;
	/**
	* 别名
	*/
	@ApiModelProperty("别名")
	private String alis;
	/**
	* 预约标志  0 待审核 1 已提交   2 违约
	*/
	@ApiModelProperty("预约标志  0 待审核 1 已提交   2 违约")
	private String aplStas;

4、启动 SpringBoot 应用

SpringBoot 启动成功后，访问 http://localhost:8080/你的项目名/swagger-ui.html

swagger2常用注解

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表