springboot集成swagger2

---

1、前后端分离

两个（两拨）工程师，两个代码库，两个服务器，约定好的接口交互规范，进行项目的同步开发，开发效率高，开发人员专一，产品质量高。

1.1、前端工程师

我相信人都是外貌协会的，每个人找另一半的时候肯定是先重外貌后重内涵（对于这句话，不要犟，犟也没用，这是事实，不容反驳），所以呢，绚丽的页面效果，良好的用户体验，完美的系统兼容等美丽的外衣由我来完成，请后端工程师肌肉锻炼结实，需要你秀肌肉的时候，不要打我脸。

1.3、后端工程师

施瓦辛格是我的榜样，肌肉（高并发，高可用，高性能和各种业务逻辑）练的杠杠的，完美的线条我来打造，请前端工程师能生的一副好面孔，只要你能搭讪成功，我就能把他拿下。

1.4、完美产品

由于前后端分离，每位成员都在进行自己擅长的工作，毕竟术业有专攻嘛，所以最终成品想象中的应该是下面这样的

---

2、痛点

2.1、文档更新不及时

由于前后端独立开发，对于前后端接口规范需要出示详细的接口文档，当接口需要变动时，前后端人员无法做到“及时协商，尽早解决”，多数情况开发人员将大部分精力投入到业务上，导致接口文档更新不及时（多数成分是懒），导致前端调用接口与后端实际接口规范不一致。

2.2、接口测试不方便

前后端分离后，前端项目开发可以根据接口文档返回的数据格式，通过mock数据进行模拟返回；但是对于后端工程师依然需要软件工具（postman）等进行接口测试，接口入参比较多的情况下，测试比较麻烦。

---

3、swagger基础配置

前后端分离好处不言而喻，但也产生了一些问题，为了解决这些痛点，swagger应运而生。

3.1、官网

地址：Swagger官网

3.2、搭建项目

我这里搭建了一个springboot项目，任何业务不都不需要掺杂，搭建一个干干净净的工程即可。

3.3、导入依赖

使用swagger需要导入相应的依赖，其中包括swagger的ui依赖，有助于我们跟方便的测试接口。

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.9.2version>
dependency>

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.9.2version>
dependency>

3.4、Swagger2配置

其实此配置文件内部无需写任何东西，只需要将此配置文件交给spring管理，并在此配置文件上开启swagger即可使用

package com.angler.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
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 angler
 * @version 1.0
 * @date 2021/1/2 3:21
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
     
    /**
     * @param environment 用于获取swagger的使用环境，如果.enable(flag)不设置可以不传此参数，那么第一步也不需要
     * @return
     */
    @Bean
    public Docket docket(Environment environment){
     
        /**
         * 第一步：判断项目环境
         * 此环境配置读取的是yaml中的 spring.profiles.active:dev
         */
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
        /**
         * 第二步：整合所有
         */
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//是否启用swagger,false则swagger不能访问
                .select()
                //RequestHandlerSelectors配置要扫描接口的方式
                //1、basePackage指定要扫描的包 2、any()扫描全部 3、none()全部不扫描
                //4、withClassAnnotation 扫描类上的注解(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                //5、withMethodAnnotation 扫描方法上的注解（RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)）
                .apis(RequestHandlerSelectors.basePackage("com.angler.swagger"))
                //paths()过滤路径 1、any() 2、none() 3、regex() 正则过滤 4、ant() 包过滤
//                .paths(PathSelectors.ant("/angler/**"))
                .build();//工厂模式
    }
    /**
     * 配置swagger信息
     * @return
     */
    private ApiInfo apiInfo(){
     
        Contact contact = new Contact("Angler LU","https://blog.csdn.net/m0_37895651","[email protected]");
        return new ApiInfo("springboot集成swagger2","创建人  Angler LU","1.0","https://blog.csdn.net/m0_37895651",
                contact,"","",new ArrayList<>());
    }
}

3.5、测试

访问地址：http://localhost:8080/swagger-ui.html
如果出现如下界面说明swagger已经配置成功了。

4、业务接口

4.1、参数实体user

package com.lusong.swagger.bean;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @author Angler LU
 * @version 1.0
 * @date 2020/11/4 11:24
 *
 * 注：对于@ApiModel @ApiModelProperty此注解只是对实体的api文档的注释，
 *      即使不写这几个注解也不影响，只是没有中文注释仅此而已
 *		只要接口返回值中有此实体都会显示在swagger的model中
 *      对于属性为private的是不会显示在swagger界面上的
 */
@ApiModel(value = "用户实体类")
@Data
public class User {
     
    @ApiModelProperty(value = "用户名")
    public String userName;
    @ApiModelProperty(value = "密码")
    public String password;
}

4.2、接口Controller

package com.lusong.swagger.controller;

import com.lusong.swagger.bean.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author Angler LU
 * @version 1.0
 * @date 2020/11/3 20:36
 */
@Api(value = "类接口描述")//这是给接口类添加注释的
@RestController
public class HelloController {
     

    @ApiOperation(value = "接口方法描述1")//这是给接口方法添加注释的
    @GetMapping(value = "/hello")
    public String hello(){
     
        return "hello";
    }
    /**
     * 只要接口的返回值中存在实体，此实体就会被swagger扫描到
     * @return
     */
    @ApiOperation(value = "接口方法描述2")//这是给接口方法添加注释的
    @GetMapping(value = "/user")
    public User user(){
     
        return new User();
    }

    @ApiOperation(value = "接口方法描述3")//这是给接口方法添加注释的
    @GetMapping(value = "/getValue")
    public String getValue(@ApiParam(value = "用户传参描述") @RequestParam("userName") String userName){
     
        return "我是用户="+userName;
    }
}

以上所有的@Api相关的注解，无论存在与否都不会影响swagger的扫描，只是对swagger的api文档添加注释用的，别无他用

4.3、接口测试

地址：http://localhost:8080/swagger-ui.html

我如同一直蜗牛向着更高的地方爬，虽然慢，但我从未停止。