1、什么是Swagger

      Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。
      Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
      Swagger的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

2、为什么要使用Swagger

想想我们之前在项目中的接口，通常都要给每个接口写对应的接口文档，如果项目中的接口都是内部使用并且开发团队都在一起，也许可以省掉写接口文档，开发一个新的接口直接口头表述，后面自己去看这些接口都不知道是干什么用，更别说接口给外部团队使用了。之前编写接口文档可能都是用Word文档写或者用javadoc注释生成文档。两种都比较麻烦，手写耗时耗力，生成文档每次都要编译一遍。使用Swagger则可以快速的生成文档。

3、使用Swagger的好处

前后端分离开发
API文档非常明确
测试的时候不需要再使用URL输入浏览器的方式来访问Controller
传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件）
Swagger与SpringBoot的集成简单

4、将Swagger与SpringBoot集成

4.1 添加依赖

<!-- spring boot 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>

4.2 创建Swagger配置类

/**
 * Swagger2的配置类
 * 线上环境：默认不显示任何接口和项目信息
 * 开发，测试环境：默认显示所有接口信息
 */
@Component
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.isOpen}")
    private boolean isOpenSwagger;

    @Value("${deploy.env}")
    private String env;

    @Bean
    public Docket createRestApi() {
        //只有当[启用swagger]和[非prod环境]，才配置swagger的相关信息，线上环境强制不开启
        if(isOpenSwagger && !"prod".equals(env)){
            Docket docket = new Docket(DocumentationType.SWAGGER_2);
            //测试环境需要补充下面的前缀才能正常访问接口
            if("test".equals(env)){
                docket.pathMapping("/");
            }
            if("dev".equals(env)){
                docket.pathMapping("/");
            }           

            return  docket.apiInfo(apiInfoDev())
                    .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                    .build();

        }else{
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfoProd())
                    .select()
                    .apis(RequestHandlerSelectors.none())
                    .paths(PathSelectors.none())
                    .build();
        }

    }

    private ApiInfo apiInfoDev() {
        return new ApiInfoBuilder()
                .title("swagger")
                .description("spring boot 集成 swagger")
                .termsOfServiceUrl("/")
                .version("1.0")
                .build();
    }

    private ApiInfo apiInfoProd() {
        return new ApiInfoBuilder()
                .title("")
                .description("")
                .termsOfServiceUrl("")
                .version("")
                .build();
    }

/**
 * Swagger的入口
 * 可以配置指定的url访问swagger2生成的接口页面，可以在这里自定义校验逻辑
 */
@Controller
@ApiIgnore
public class SwaggerController {
    @GetMapping(value = "/swagger")
    public String index(){
        //这里可以写校验逻辑
        return "redirect:/swagger-ui.html";
    }
}

4.3 编写Controller

在这里编写自己的RESTFull风格的接口，跟正常开发没什么区别，只是要在对应的类、函数、参数上加上Swagger注解就可以了。注解说明：
1. @Api：用在类上，说明该类的作用
2. @ApiOperation：用在方法上，说明方法的作用
3. @ApiImplicitParams：用在方法上包含一组参数说明
4. @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
      paramType：参数放在哪个地方
         header请求参数的获取：@RequestHeader
         query请求参数的获取：@RequestParam
         path（用于restful接口）–>请求参数的获取：@PathVariable
         body（不常用）
         form（不常用）
      name：参数名
      dataType：参数类型
      required：参数是否必须传
      value：参数的意思
      defaultValue：参数的默认值
5. @ApiResponses：用于表示一组响应
6. @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
      code：数字，例如400
      message：信息，例如”请求参数没填好”
      response：抛出异常的类
7. @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
8. @ApiModelProperty：描述一个model的属性
9. @ApiIgnore：生成文档时忽略

具体其他注解及详细解释查看：
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

@RestController
@RequestMapping(value = "/test")
@Api(tags = {"Swagger模块"})
public class TestController {

    @RequestMapping(value = "/getSwagger", method = {RequestMethod.GET})
    @ApiOperation(value = "获取Swagger",notes = "spring boot Swagger")
    public String getString (){
        return "swagger";
       }

完成以上代码，启动SpringBoot后，在浏览器输入http://localhost:8080/swagger 就可以看到界面了。

spring-boot集成swagger