Spring Boot开发（八）Swagger2的集成和使用

前后端分离

前端 -> 前端控制层、视图层

后端 -> 后端控制层、服务层、数据访问层

API文档

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。

一个项目组可能由前端、后端、安卓、IOS等众多的开发人员或者众多开发团队组成。前端和后端唯一联系，变成了API接口；API文档自然就成了前后端开发人员联系的纽带，变得尤为的重要，

产生的问题

现在都奉行前后端分离开发和微服务大行其道，分微服务及前后端分离后，内部的 API 共同成本巨大，开发的沟通成本就增加了

• 接口多且复杂；
• 细节之处繁杂：通讯协议、参数、返回值、接口说明、路径等；
• 接口的维护。功能接口是随着时间迭代升级的，因此这增加了接口文档的管理成本。

因此，团队内部的沟通，一直都是开发人员的一个痛点。而手动编写 api 文档，如有在Word上写的，有在对应的项目目录下readme.md上写的，不仅效率低，而且容易遗漏、不能及时同步更新。

Swagger2介绍

Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。

现如今市场上书写API文档的工具有很多，常见的有 postman、yapi、阿里的RAP 但是能称之为框架的，估计也只有swagger了。目前在后端领域，基本上是swagger的天下了。

swagger 优缺点

• 集成方便，功能强大，号称世界上最流行的API框架
• 直接运行，在线测试API
• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
• 支持多种语言 （如：Java，PHP等）
• 代码耦合，需要注解支持，对接口的污染较大，但不影响程序性能

SpringBoot整合Swagger2

前期准备

1. 首先创建一个基础的SpringBoot web项目。您可以通过 Spring Initializr 页面生成一个空的 Spring Boot 项目，或者通过idea创建一个SpringBoot项目

2. 添加依赖

3. 1. Spring Boot的Web依赖

      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
      </dependency>

   2. 集成swagger2

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

4. 1. 集成Swagger UI

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

4、编写HelloController，测试确保运行成功！

配置Swagger

主要是添加注解@EnableSwagger2和定义Docket的bean类。

/**
             * 集成swagger2  解决前后端分离 弊端：不能及时协商+尽早解决的问题
             *      使用swagger总结:
             *          通过swagger 给一些比基奥难理解的接口或属性，增加注释信息
             *          接口文档实时更新
             *          可以在线测试
             *      安全问题:
             *          正式上线的时候  记得关闭swagger
             */
            @Configuration//加载到springboot配置里面
            @EnableSwagger2//开启swagger2
            public class SwaggerConfig {
   
                /**
                 * 配置swagger2
                 * 注册一个bean属性
                 * swagger2其实就是重新写一个构造器，因为他没有get set方法\
                 * enable() 是否启用swagger false swagger不能再浏览器中访问
                 * groupName()配置api文档的分组  那就注册多个Docket实例 相当于多个分组
                 * @return
                 */
                @Bean
                public Docket docket() {
   
            
                    return new Docket(DocumentationType.SWAGGER_2)
                            .apiInfo(apiInfo())
                            .groupName("qlh")//组名称
                            .enable(true)
                            .select()
                            /**
                             * RequestHandlerSelectors配置扫描接口的方式
                             *      basePackage 配置要扫描的包
                             *      any 扫描全部
                             *      none 不扫描
                             *      withClassAnnotation 扫描类上的注解
                             *      withMethodAnnotation 扫描方法上的注解
                             */
                            .apis(RequestHandlerSelectors.basePackage("com.tinygray.madison.controller"))
                            /**
                             * paths() 扫描过滤方式
                             *      any过滤全部
                             *      none不过滤
                             *      regex正则过滤
                             *      ant过滤指定路径
                             */
            //                .paths(PathSelectors.ant("/login/**"))
                            .build();
                }
            
                /**
                 * 配置swagger2信息 =apiInfo
                 * @return
                 */
                public ApiInfo apiInfo(){
   
                    /*作者信息*/
            //        Contact contact = new Contact("XXX", "http://baidu.com", "email");
                    Contact contact = new Contact("", "", "");
                    return new ApiInfo(
                            "XXX的API接口",
                            "company接口",