9、Swagger

Swagger

　　接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项 目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接 口文档和实际情况不一致。

很多人员会抱怨别人写的接口文档不规范，不及时更新。当时当 自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢 记于心。

如果接口文档可以实时动态生成就不会出现上面问题。

Swagger 可以完美的解决上面的问题。

Swagger 简介：

---

　　Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设 计，构建，记录和使用 REST API。

Swagger 工具包括的组件：

• Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。
• Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。
• Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端 库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形 式的接口文档，同时也可以生成多种言语的客户端和服务端代码。

Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多 信息，也会保存请求的实际参数数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目 和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档， 以及生成各端代码。

Swagger集成

1、新建springbootweb项目导入maven依赖

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

2、创建Swagger配置：config/SwaggerConfig.java

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author zhangzhixi
 */
@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {

}

3、测试访问

访问：localhost:8080/swagger-ui.html

 swagger首页DIY：

在SwaggerConfig进行如下配置即可自定义Swagger配置

package com.zhixi.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

/**
 * @author zhangzhixi
 */
@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {

    // 配置Swagger
    @Bean
    public Docket docket() {
        // 返回docket的bean实例
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    // 配置swagger的信息-api-info
    private ApiInfo apiInfo() {
        // 作者说明
        Contact contact = new Contact("志喜", "https://www.cnblogs.com/zhangzhixi", "1820712542@qq.com");
        return new ApiInfo(
                "志喜的SwaggerAPI文档",
                "人生没有白走的路~",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

Swagger扫描接口：

---

// 配置Swagger
@Bean
public Docket docket() {
    // 返回docket的bean实例
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(true)//是否启用Swagger，false则不启用
            .select()
            //RequestHandlerSelectors,配置要扫描接口的方式
            //basePackage，指定扫描包
            //.apis(RequestHandlerSelectors.any()),扫描全部
            //.apis(RequestHandlerSelectors.none()),不扫描
            //withMethodAnnotation(GetMapping.class)) //扫描类上的注解
            //withClassAnnotation(GetMapping.class)) //扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.zhixi.controller"))
            //Path过滤路径
            //.paths(PathSelectors.ant("/com/**"))
            .build();
}

实现开发环境中使用Swagger，运行上线环境中不使用Swagger：

 // 配置Swagger
 @Bean
 public Docket docket(Environment environment) {
     //设置要显示的Swagger环境
     Profiles profiles = Profiles.of("dev", "test");
     //获取项目的环境：判断是否处在自己设定的环境中
     boolean flag = environment.acceptsProfiles(profiles);
     // 返回docket的bean实例
     return new Docket(DocumentationType.SWAGGER_2)
             .apiInfo(apiInfo())
             .enable(flag)//是否启用Swagger，false则不启用
}

分组以及注释：

分组管理：

　　通过groupName("")配置多个Docket，(在多人开发中，每个开发者配置一个自己的Swagger，方便管理)

@Bean
public Docket docket1() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("test1");
}
@Bean
public Docket docke2() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("test2");
}
@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("test3");
}

Swagger常用注解：

controller中：

 @Api(tags = "请求控制类")  // 给controller类加注释

 @ApiOperation("用户赋值请求")  //给controller请求加注释

pojo实体类中：

  @ApiModel("用户类")  // 标注类的信息

 @ApiModelProperty("用户名")  // 标注属性信息

public String username;

swagger 测试：

　　controller请求：

 @ApiOperation("用户赋值请求")
 @RequestMapping("/user")
 public User getUser1(User user) {
     return user;
 }