【SpirngBoot組件（1）】Swagger集成

個人學習筆記分享，當前能力有限杨伙，請勿貶低，菜鳥互學萌腿，大佬繞道

如有勘誤限匣，歡迎指出和討論，本文后期也會進行修正和補充

前言

使用Swagger可以方便快捷的查看和調試接口毁菱，而不再需要借助其他第三方工具（如postman）膛腐，更不需要在茫茫代碼中尋找接口睛约，其相關注解也一定程度上提高了代碼可讀性。

因此哲身，swagger幾乎已經算的上是一個項目的必要組件了辩涝。

1.介紹

1.1.Swagger、Spring勘天、SpringFox

Swagger是一個流行的API框架怔揩，對整個API開發(fā)周期提供解決方案，包括設計脯丝、編碼和測試等等商膊，幾乎支持所有語言。
Spring作為常用的Java開發(fā)框架宠进，不做多余敘述
SpringFox是一個基于Spring的組件晕拆，用于Swagger集成至SpringMVC，后發(fā)展至SpringFox材蹬，Springfox-swagger2則是其中一個組件
Springfox-Swagger-UI顧名思義則是一個UI組件实幕，用于展示相關數(shù)據(jù)

總結：

Swagger是API解決方案
Spring是Java框架
SpringFox是基于Java的Swagger實現(xiàn)
Springfox-Swagger-UI是配套的UI

1.2.用途

前后端分離：前端只需要通過Swagger即可查找并調試接口
API整理：暴露給外部的接口全部展示在Swagger，方便查找和整理
增強代碼可讀性：相關注解在后端也會使代碼可讀性更好堤器，相當于充當了注釋的作用

2.集成

目前SpringFox已經更新至3.0版本昆庇，修復了大量問題，關鍵是配置方法做出了改變闸溃，故將SpringFox2與SpringFox3分開記錄

2.1.swagger2（主流版本）

添加依賴

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

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

前者為swagger2依賴整吆，后者為ui，后者可以更換為其他ui辉川，此處不做多述

創(chuàng)建swagger配置文件

@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
public class SwaggerConfig {
    @Bean // 配置docket以配置Swagger具體參數(shù)
    public Docket docket(Environment environment) {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())// 關聯(lián)配置文檔
                .enable(true)// 是否啟用
                .select()//掃描方法
                .apis(RequestHandlerSelectors.basePackage("com.yezi_tool.basic_project.controller"))//掃描包路徑
                .paths(PathSelectors.any())//路徑過濾
                .build();//構建
    }

    // 配置文檔信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成")
                .description("API描述")
                .contact("聯(lián)系人名字")
                .version("1.0")
                .build();
    }
}

啟動項目后表蝙，打開網址http://localhost:8080/swagger-ui.html，請自行修改端口和路徑

2.2.swagger3版本

添加依賴

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

僅此一個依賴

創(chuàng)建swagger配置文件

@Configuration
@EnableOpenApi
@Profile({"dev", "test"})
public class Swagger3Config {
    @Bean // 配置docket以配置Swagger具體參數(shù)
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)//文檔類型
                .apiInfo(apiInfo())// 關聯(lián)配置文檔
                .select()//掃描方法
                .apis(RequestHandlerSelectors.basePackage("com.yezi_tool.basic_project.controller"))//掃描包路徑
                .paths(PathSelectors.any())//路徑過濾
                .build();//構建
    }

    // 配置文檔信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("聯(lián)系人名字", "http://xxx.xxx.com/聯(lián)系人訪問鏈接", "聯(lián)系人郵箱");
        return new ApiInfo(
                "Swagger學習", // 標題
                "學習演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/組織鏈接", // 組織鏈接
                contact, // 聯(lián)系人信息
                "Apach 2.0 許可", // 許可
                "許可鏈接", // 許可連接
                new ArrayList<>()// 擴展
        );
    }
}

啟動項目后乓旗，打開網址http://localhost:8080/swagger-ui/index.html勇哗，請自行修改端口和路徑

2.3.版本差異

swagger3進行了大量更新與修復，不做多述
swagger3僅需一個依賴寸齐，將swagger和UI合并
配置文件的注解欲诺，swagger2需要@EnableSwagger2，而swagger3需要@EnableOpenApi
配置文件的ApiInfo構造方法變更渺鹦，小問題
項目默認地址變更扰法，swagger2的地址是/swagger-ui.html，swagger3的地址是swagger-ui/index.html
部分方法改動毅厚，如2.5的全局參數(shù)

2.4.配置文件額外參數(shù)

通常上述參數(shù)已滿足需求塞颁，當然還提供了其他參數(shù)供開發(fā)者選擇，兩個版本的自定義參數(shù)基本一致

注解@Profile：枚舉適用的運行環(huán)境，通常僅在開發(fā)環(huán)境和測試環(huán)境中啟用祠锣，則可使用@Profile({"dev", "test"})
配置文檔信息：請根據(jù)需求修改酷窥，不做多述
docket對象方法
- enable()：是否啟用swagger，參數(shù)為true/false伴网，但通常用注解@Profile控制
- api()：指定包掃描路徑蓬推，參數(shù)形如RequestHandlerSelectors.basePackage("com.test.api")，也可以根據(jù)自身需求調整澡腾，其余形式參數(shù)如下
  - RequestHandlerSelectors.any()：掃描所有沸伏，項目中的所有接口都會被掃描到
  - RequestHandlerSelectors.none() ：不掃描接口
  - RequestHandlerSelectors.withMethodAnnotation(final Class<? extends Annotation> annotation)： 通過方法上的注解掃描，如withMethodAnnotation(GetMapping.class)只掃描get請求
  - RequestHandlerSelectors.withClassAnnotation(final Class<? extends Annotation> annotation)： 通過類上的注解掃描动分，如.withClassAnnotation(Controller.class)只掃描有controller注解的類中的接口
  - RequestHandlerSelectors.basePackage(final String basePackage) ： 根據(jù)包路徑掃描接口
- paths()：指定url路徑過濾毅糟，參數(shù)形如PathSelectors.ant("/login/**")，也可以根據(jù)自身需求調整澜公，其余形式參數(shù)如下
  - PathSelectors.any()： 任何請求都掃描
  - PathSelectors.none() ： 任何請求都不掃描
  - PathSelectors.regex(final String pathRegex) ： 通過正則表達式控制
  - PathSelectors.ant(final String antPattern) ： 通過ant()控制
- groupName()：配置分組姆另，參數(shù)為String字符串，如group 1坟乾，默認分組為default迹辐，如需設置多個分組，則實例化多個不同名的docket即可
- getGlobalOperationParameters：全局參數(shù)糊渊，不適用于swagger3，通常用于token慧脱，示例如下
```
        ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        ticketPar.name("token")
                .description("token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(ticketPar.build());
        docket.globalOperationParameters(pars)
```

2.5.全局參數(shù)（重點）

通常用于設置token渺绒，swagger3修改了相關方法，所以此處均給出示例

swagger2版本

  public Docket docket() {
        ...
      docket.globalOperationParameters(pars);
        ...
    }
            
    private List<Parameter> pars(){
        List<Parameter> pars = new ArrayList<Parameter>();
        ParameterBuilder ticketPar = new ParameterBuilder();
        ticketPar.name("token")
                .description("token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
        pars.add(ticketPar.build());
        return pars;
    }

swagger3版本

  public Docket docket() {
        ...
      docket.protocols(new LinkedHashSet<>(Arrays.asList("https", "http")))// 支持的通訊協(xié)議集合
        .securitySchemes(securitySchemes())// 授權信息設置菱鸥，必要的header token等認證信息
        .securityContexts(securityContexts());// 授權信息全局應用
        ...
    }
    /**
     * 設置授權信息
     */
    private List<SecurityScheme> securitySchemes() {
        return Collections.singletonList(new ApiKey("BASE_TOKEN", "token", "pass"));
    }

    /**
     * 授權信息全局應用
     */
    private List<SecurityContext> securityContexts() {
        return Collections.singletonList(
                SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")}))).build());
    }

3.使用

使用步驟

當然一切的前提是先集成

添加注解

實體類添加注解，實例如下

@ApiModel("登錄信息實體")
public class LoginRequest {
   @ApiModelProperty("用戶名")
   public String username;
   @ApiModelProperty("密碼")
   public String password;
}

控制器添加注解娶靡，實例如下

@Controller
@RequestMapping("/testController")
@Api(tags = "測試")
public class TestController {
}

接口方法添加注解牧牢，實例如下

    @ApiOperation("測試swagger")
    @PostMapping("/testSwagger")
    @ResponseBody
    public LoginRequest testSwagger(@ApiParam(required = false, value = "登錄實體") @RequestParam(required = false) @RequestBody LoginRequest loginRequest) throws Exception {
        if (loginRequest == null) {
            loginRequest = new LoginRequest();
        }
        return loginRequest;
    }

swagger測試，沒什么好貼圖的，就省了吧塔鳍。伯铣。

4.傳送門

Swagger2集成方案

Swagger3集成方案

SpringFox官方主頁

BB兩句

為啥總感覺swagger3變丑了好多。轮纫。腔寡。

作者：Echo_Ye

WX：Echo_YeZ

email ：echo_yezi@qq.com

個人站點：在搭了在搭了。蜡感。蹬蚁。（右鍵 - 新建文件夾）