SpingBoot 集成 Swagger2 --超nice！！！

从前：

开发人员创建一份 RESTful API 文档来用来记录所有的接口细节。

但是，会有一下问题的出现：

• API 接口众多，细节复杂，需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等，想要高质量的完成这份文档需要耗费大量的精力；

• 难以维护。随着需求的变更和项目的优化、推进，接口的细节在不断地演变，接口描述文档也需要同步修订，可是文档和代码处于两个不同的媒介，除非有严格的管理机制，否则很容易出现文档、接口不一致的情况；

现在：

Swagger2 诞生！！！

Swagger2 可以从根本上解决上述问题，它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：

1. 接口文档在线自动生成，文档随接口变动实时更新，节省维护成本

2. 支持在线接口测试，不依赖第三方工具

真的很happy！！！

迫不及待的人儿，下面就来说说怎么完美的使用它吧！

1、pom.xml 添加 Maven 依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

注：

springboot项目整合swagger要注意两者的版本，springboot项目的版本低，相应的swagger版本不能太高，反之亦然，避免项目报错,我的springboot版本为2.2.2，swagger版本为2.2.2，项目启动就会报如下错误：这个问题的解决办法就是直接将pom文件中的swagger版本换成2.9.2就可以了！

 

2、创建 Swagger2.java

package com.kismet.mongotext.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author ganqizhi
 * @date 2020/9/11 11:27 上午
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kismet.mongotext.Controller"))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("kismet的测试服务") //设置文档的标题
                .description("kismet的测试服务 API 接口文档") // 设置文档的描述
                .version("1.0") // 设置文档的版本信息-> 1.0.0 Version information
                .build();
    }
}

Swagger2.java 配置类的内容很少，配置完成后也很少变化，了解即可。

如上代码所示，通过 @Configuration 注解，让 Spring 加载该配置类。再通过 @EnableSwagger2 注解来启用Swagger2。成员方法 createRestApi 函数创建 Docket 的Bean之后，apiInfo() 用来创建该 Api 的基本信息，这些基本信息会展现在文档页面中。select() 函数返回一个 ApiSelectorBuilder实例用来控制哪些接口暴露给 Swagger 来展现，我这里采用指定扫描的包路径来定义，Swagger 会扫描该包下所有 Controller 定义的 API，并产生文档内容，但除了被 @ApiIgnore 指定的请求。

 

3、API 接口编写

在完成上述配置后，就已经可以产生文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。

package com.kismet.mongotext.Controller;


import com.kismet.mongotext.Service.UserService;
import com.kismet.mongotext.config.PageableVo;
import com.kismet.mongotext.config.RequestVo;
import com.kismet.mongotext.entity.MongoUser;
import com.kismet.mongotext.entity.MysqlUser;
import com.kismet.mongotext.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpSession;
import java.util.List;

/**
 * @author ganqizhi
 * @date 2020/9/4 2:52 下午
 */
@RestController
@RequestMapping("/user")
@Api(description = "生产者进程API接口")
public class UserController {

    @Autowired
    private UserService userService;

    //读取mongodb用户信息同步给mysql
    @ApiOperation("读取mongodb用户信息同步给mysql")
    @GetMapping("/snycUser")
    public List<MysqlUser> findAll(){
        return userService.snycUser();
    }

    //添加mongodb用户信息
    @ApiOperation("添加mongodb用户信息")
    @PostMapping("/addUser")
    public MongoUser addUser(@RequestBody User user){
        return userService.addUser(user);
    }

    //分页查询mysql数据
    @ApiOperation("分页查询mysql数据")
    @PostMapping("/findPage")
    public List<MysqlUser> findByPage(@RequestBody PageableVo<RequestVo,User> users){
        return userService.findByPage(users);
    }


    @ApiOperation("添加mongodb用户信息")
    @PostMapping("/findByMongo")
    public List<MongoUser> findByMongo(@RequestBody PageableVo<RequestVo,User> users){
        return  userService.findMongo(users);
    }
}

Swagger 通过注解定制接口对外展示的信息，这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型：

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
• @ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
•  

4、启动 SpringBoot 应用

SpringBoot 启动成功后，访问http://localhost:8021/swagger-ui.html    //端口号需根据自己的端口号进行修改

展开类维度的接口列表，如 user-controller，页面会列出该类中定义的所有接口。点击任意接口，可查看该接口的 url 路径、请求类型、参数描述和返回码说明等信息。

点击右上角的 “Try it out！”按钮，写入请求信息，点击 Execute 按钮完成一次请求调用！

 

这就完美的完成了！！！