SpringBoot集成swagger2-蒲公英云

一: 简介

什么是swagger ？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。目前来说swagger一共有两个版本，且区别还挺大，第一个版本就是swagger-ui也就是swagger1；第二个版本是springfox-swagger也就是swagger2；

本篇只说Swagger2在线文档框架，因为相对swagger1来说，本人觉得使用swagger2开发效率更好，且使用更方便，它是通过注解的方式生成在线文档，不同于swagger1 还需写index.xml和ymal配置文件。

为什么要用swagger ?

因为自前后端分离后，写接口文档可以说是必不可少得工作。我们在理想状态下，只需设计好接口文档，然后通过前/后端小伙伴按规则开发，开发好之后对接上线就OK了，当然，这样的流程仅限于理想状态，而在实际开发过程中，我们只能不断的改丶改丶改 [ 就问你炸不炸 ] ，所以我们如何“优雅”的写接口文档呢？使用swagger就是其中一种方式，这里只介绍swagger2。

下面开始 SpringBoot + Maven + Swagger2 的使用

二：集成，测试

一：添加依赖

<!--引入swagger2依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.0</version>
</dependency>

二：swagger2信息配置

创建一个Swagger2Config类用于swagger的基本配置（自定义命名，想咋写咋写）

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
/**
 * 对Swagger2的配置信息
 *
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试 API")
                .description("测试 API")
                .termsOfServiceUrl("http://127.0.0.1:8081/")
                .contact("你妈喊你回家吃饭了")
                .version("1.0")
                .build();
    }
}

这里涉及到了两个注解：

@Configuration 用于定义配置类，是JDK自带的注解，可替换xml配置文件，被注解的类内部包含有一个或多个被@Bean注解的方法，这些方法将会被AnnotationConfigApplicationContext或AnnotationConfigWebApplicationContext类进行扫描，并用于构建bean定义，初始化Spring容器。

@EnableSwagger2就是启动swagger2的相关功能。

访问：http://127.0.0.1:8081/swagger-ui.html （我这里端口是8081）

到这里我们的swagger就配置完成了，下面我们写一段测试代码。

watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mzg3NjU0OA_size_16_color_FFFFFF_t_70

三：写一个测试类

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
@Controller
@Api(description = "测试TEST")
public class Test {
    @RequestMapping("/index")
    public String Index(){
        return "index";
    }
    @ResponseBody
    @RequestMapping("test")
    @ApiOperation(value = "测试",notes = "获取",httpMethod = "GET")
    public String test(){
        return "Hello World";
    }
}

访问：http://127.0.0.1:8081/swagger-ui.html

点击：Try it out! 进行测试。 watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mzg3NjU0OA_size_16_color_FFFFFF_t_70 1

好了，一个简单的测试就完成了。

三：统一参数

我们在编写API文档的时候一般都需要统一验证请求的，就拿登陆来说，我们需要通过获取请求头header里的token来验证，对于这种情况，我们可以在controller的方法中都加上token的参数，这样虽然可以解决，但是真的很麻烦，所以我们可以通过在swagger配置类中统一处理token参数的方式来解决。

import io.swagger.annotations.ApiOperation;
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.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.List;
import static com.google.common.collect.Lists.newArrayList;
/**
 * 对Swagger2的配置信息
 *
 * @author wendell
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                ;
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试 API")
                .description("测试 API")
                .termsOfServiceUrl("http://127.0.0.1:8081/")
                .contact("你爸喊你回家吃饭了，快出来")
                .version("1.0")
                .build();
    }
    /**
     * 全局统一配置token
     * @return
     */
    private List<ApiKey> securitySchemes() {
        return newArrayList(
                new ApiKey("Authorization", "Authorization", "header"));
    }
    private List<SecurityContext> securityContexts() {
        return newArrayList(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build()
        );
    }
    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return newArrayList(
                new SecurityReference("Authorization", authorizationScopes));
    }
}

配置完成之后，重启服务器，访问swagger默认地址 http://localhost:8081/swagger-ui.html

我们可以看到比之前页面多了一个Authorization按钮，我们可以通过点击该按钮添加token值

watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mzg3NjU0OA_size_16_color_FFFFFF_t_70 2

这样在每次访问时都会将token值添加到header中，实现参数统一；

四：swagger2常用注解使用说明

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

@Api:用在请求的类上，标明该类的作用
     tags="该类的作用"
     value="无意义，不需要配置"

@ApiModel：用在响应类上，返回响应数据的信息

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
/**
 *用于响应类上，返回响应数据信息
 *
 *@ApiModel：这种一般用在post创建的时候，使用 @RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候
 *@ApiModelProperty：用在属性上，描述响应类的属性
 */
@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{
    @ApiModelProperty(value = "是否成功")
    private boolean success=true;
    @ApiModelProperty(value = "返回对象")
    private Object data;
    @ApiModelProperty(value = "错误编号")
    private Integer errCode;
    @ApiModelProperty(value = "错误信息")
    private String message;
    //get/set方法
}

用在请求方法上，说明该方法的作用的注解

@ApiOperation( 方法的用途、作用
     value="方法用途、作用"
     notes="方法备注说明"
     httpMethod="请求方式(get/set)"
 )
@ApiImplicitParams({ 用于参数说明
     @ApiImplicitParam( 指定一个请求参数的配置信息 
        name="参数名" ,
        value="参数的汉字说明、解释",
        required="参数是否必须传",
        paramType="参数放在哪个地方",
            · header(请求参数的获取：@RequestHeader)
            · query(请求参数的获取：@RequestParam)
            · path（用于restful接口  请求参数的获取：@PathVariable）
            · body（不常用）
            · form（不常用）    
        dataType="参数类型，默认String，其它值dataType=Integer", 
        defaultValue="参数的默认值"
    )
})：
@ApiOperation(value = "作用",notes = "备注")
@ApiResponses({   //在@ApiResponses中，错误的响应信息
    @ApiResponse(code=400,message="参数出错"),
    @ApiResponse(code=404,message="Not Found")
})