Swagger2学习与集成

Author: haoransun
Wechat: SHR—97

1 Swagger2介绍

     现在都奉行前后端分离和微服务大行其道，分微服务及前后端分离后，前后端开发的沟通成本就增加了。所以一款强大的RestFul API 文档则十分重要，而目前在后端领域，基本上就是Swagger的天下了。
     Swagger是一款RestFul接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RestFul风格的Web服务，加上Swagger-ui，可以有很好的呈现。

2 Spring Boot 集成

这里选用的Swagger版本：2.8.0

2.1 POM依赖

<!--swagger-->
<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>

2.2 编写配置文件(Swagger2Config.java)

主要是添加注解 @EnableSwagger2 和定义 Docket 的 bean类。

@EnableSwagger2
@Configuration
public class SwaggerConfig{

    //是否开启Swagger,正式环境一般是需要关闭的，可根据SpringBoot的多环境配置进行设置
    @Value(value="${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi(){
              return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
              //是否开启
             .enable(swaggerEnabled).select()
             //扫描的路径包
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
            //指定路径处理 PathSelectors.any()代表所有的路径
            .paths(PathSelectors.any())
            .build()
            .pathMapping("/");
     }

     private ApiInfo apiInfo(){
             return new ApiInfoBuilder()
            .title("SpringBoot-Swagger2集成Demo ")
            .description("Allen")
            // 作者信息
            .contact(new Contact("haoransun","demo.com","Wechat: SHR---97"))
            .version("1.0.0")
            .build();
     }
}

2.3 添加文档内容(一般是在Controller， 请求参数上进行注解)

常用的注解@Api、@ApiOperation、@ApiModel、@ApiModelProperty示例中有进行标注，对于其他注解，大家可自动谷歌，毕竟常用的就这几个了。有了swagger之后，原本一些post请求需要postman这样的调试工具来进行发起，而现在直接在页面上就可以进行调试了，是不是很爽！对于服务的调用者而已，有了这份api文档也是一目了然，不需要和后端多少沟通成本，按着api说明进行前端开发即可。

@ApilmplicatParams(name = “”,value=””,dataType=””,paramType=””)

paramType:
query—@RequestParam
header—@RequestHeader
path —@PathVariable (RestFul风格)

ParameterBuilder tokenPar = new ParameterBuilder();
List pars = new ArrayList();
tokenPar.name(“Authorization”).description(“令牌”)
.modelRef(new ModelRef(“string”)).parameterType(“header”)
//header中的token参数非必填，传空也可以
.required(false).build();
//根据每个方法名也知道当前方法在设置什么参数
pars.add(tokenPar.build());