一、Swagger2 简介

  由于Spring Boot能够快速开发、便捷部署等特性，相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。
  这样一来，我们的RESTful API就有可能要面对多个开发人员或多个开发团队：IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：
  由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。
  随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。
  为了解决上面这样的问题，本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示：

Swagger2

二、Maven依赖

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--swagger插件-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.3</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>2.9.2</version>
        </dependency>

三、配置文件

1. 配置文件

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config {
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("默认接口")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxxx.admin.modules.system.controller.admin"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXXXXXXXX")
                .description("描述：XXXXXXX！")
                .termsOfServiceUrl("http://www.xtsz.com/")
                .contact(new Contact("marquis","http://www.XXXXXX.com/","XXXXXXX@qq.com"))
                .version("版本号:1.0.0")
                .build();
    }
    /**
     *  安全认证
     * @return
     */
    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Lists.newArrayList(new SecurityReference("BearerToken", authorizationScopes));
    }
    List<SecurityReference> defaultAuth1() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Lists.newArrayList(new SecurityReference("BearerToken1", authorizationScopes));
    }
}

2. 权限设置

 // swagger-ui
                .antMatchers("/swagger-ui.html").permitAll()
                .antMatchers("/doc.html").permitAll()
                .antMatchers("/swagger-resources/**").permitAll()
                .antMatchers("/images/**").permitAll()
                .antMatchers("/webjars/**").permitAll()
                .antMatchers("/v2/api-docs").permitAll()
                .antMatchers("/configuration/ui").permitAll()
                .antMatchers("/configuration/security").permitAll()
 // swagger-ui

3. 浏览访问:

http://localhost:8000/doc.html

浏览访问

4. 全局设置

全局设置

四、相关注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
　@Api：修饰整个类，描述Controller的作用
　@ApiOperation：描述一个类的一个方法，或者说一个接口
　@ApiParam：单个参数描述
　@ApiModel：用对象来接收参数
　@ApiProperty：用对象接收参数时，描述对象的一个字段
　@ApiResponse：HTTP响应其中1个描述
　@ApiResponses：HTTP响应整体描述
　@ApiIgnore：使用该注解忽略这个API
　@ApiError ：发生错误返回的信息
　@ApiParamImplicit：一个请求参数
　@ApiParamsImplicits: 多个请求参数

五、注解使用

1. 实体类注解
   @ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
   value–字段说明
   name–重写属性名字
   dataType–重写属性类型
   required–是否必填
   example–举例说明
   hidden–隐藏

@Data
@ApiModel
public class LoginUser {
    @NotNull(message = "账号不能为空")
    @ApiModelProperty(value = "账号", required = true)
    private String username;

    @NotNull(message = "密码不能为空")
    @ApiModelProperty(value = "登录密码", required = true)
    private String password;

    @ApiModelProperty(value="记住密码 0不记 1记住",required = true,example="0")
    private Integer rememberMe;
}

2. 控制器类注解
   @Api：用在请求的类上，表示对类的说明
   tags="说明该类的作用，可以在UI界面上看到的注解"
   value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@Api(tags = {"1、用户登录"})
public class AuthController {
}

3. 控制器方法注解
   @ApiOperation() 用于方法；表示一个http请求的操作
   value用于方法描述
   notes用于提示内容
   tags可以重新分组（视情况而用）

    @PostMapping("/login")
    @ApiOperation(value = "1、用户登录", notes = "使用账号密码登录", httpMethod = "POST")
    public String login(@RequestBody LoginUser loginUser){
}

4. @ApiImplicitParam
   在 Rest 接口上单独使用
   @ApiImplicitParam 在 Rest 接口上单独使用的时候，表示单个请求参数
   在 Rest 接口上和 @ApiImplicitParams 组合使用
   @ApiImplicitParam 在 Rest 接口上和 @ApiImplicitParams 组合时候，表示多个请求参数
   属性

paramType属性:
header : 请求参数的获取：@RequestHeader
query : 请求参数的获取：@RequestParam
path : 请求参数的获取：@PathVariable
body : 请求参数的获取：@RequestBody
form : 不常用

5. @ApiImplicitParams
   在 Rest 接口方法上使用来指定请求参数
   属性

    @GetMapping("/getUserName")
    @ApiOperation(value = "1、获取账号名称", notes = "使用账号密码登录", httpMethod = "GET")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "账号名称", dataType = "String"),
            @ApiImplicitParam(name = "password", value = "密码", dataType = "String")})
    public String getUserName(String username, String password, HttpServletRequest request) {
        String str = "本地端口：" + request.getLocalPort() + "远程端口：" + request.getRemotePort() + "服务端口：" + request.getServerPort();
        return "用户名为:" + username + "密码：" + password + "---->" + str;
    }

六、权限控制

生产环境不可调用查看。
在Swagger2的配置类上添加注解。

@Profile({"dev", "test"})