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依賴，有助於我們跟方便的測試介面。

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</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","lusong2111@163.com");
        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

我如同一直蝸牛向著更高的地方爬，雖然慢，但我從未停止。