SpringBoot集成Swagger2

2020 年 12 月 15 日
筆記
Java web學習

一、是什麼

　　當下很多公司都採取前後端分離的開發模式，前端和後端的工作由不同的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文檔將會極大的提高我們的工作效率。傳統意義上的文檔都是後端開發人員手動編寫的，相信大家也都知道這種方式很難保證文檔的及時性，這種文檔久而久之也就會失去其參考意義，反而還會加大我們的溝通成本。而 Swagger 給我們提供了一個全新的維護 API 文檔的方式。

二、為什麼要使用它

　　1、程式碼變更，文檔跟著程式碼變、只需要少量的註解Swagger就可以根據程式碼自動的生成API文檔，很好的保證了文檔的實時性。

　　2、跨語言，Swagger支援40多種語言。

　　3、Swagger UI 呈現出來的是一份可以交互的API文檔，我們可以直接在文檔頁面嘗試API的調用，省去了準備複雜的調用參數的過程。

　　4、還可以將文檔規範導入相關的工具裡面（例如：Postman、SoapUI）、這些工具將會為我們自動地創建自動化測試。

三、怎麼用

　　1、在項目pom.xml裡面加入Swagger2相關的依賴

        <!--swagger2配置-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.6</version>
        </dependency>

　　2、新建Swagger2的配置類

package com.zhouhong.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
 * @ClassName: Swagger2
 * @Description:
 * @Author: 周紅
 * @NickName: Tom-shuhu
 * @Date: Created in 2020/12/15
 **/
@Configuration
@EnableSwagger2
public class Swagger2 {
    //   //localhost:8088/swagger-ui.html  原路徑
    //   //localhost:8088/doc.html  原路徑
    //配置swagger2核心配置
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2) //指定api類型位swagger2
            .apiInfo(apiInfo())                        //用於定義api文檔匯總資訊
                .select().apis(RequestHandlerSelectors
                        .basePackage("com.zhouhong.controller")) //指定生成文檔的controller
                .paths(PathSelectors.any())　　　　　　
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Tom-shushu 的項目介面api")  //文檔標題
                .contact(new Contact("周紅",  //作者
                        "www.zhouhong.icu",　　
                        "[email protected]")) //聯繫人
                .description("Tom-shushu 的項目api介面")//詳細資訊
                .version("1.0.0")//文檔版本號
                .termsOfServiceUrl("www.zhouhong.icu")//網站地址
                .build();
    }
}

　　文檔配置說明：

　　a.為任何介面生成API文檔，這種方式不必在介面方法上加任何註解，方便的同時也會因為沒有添加任何註解所以生成的API文檔也沒有注釋，可讀性不高。

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //為任何介面生成API文檔
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

　　b.為當前配置的包下controller生成API文檔

.apis(RequestHandlerSelectors.basePackage("com.troila"))

　　c.為有@Api註解的Controller生成API文檔

.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

　　d.為有@ApiOperation註解的方法生成API文檔

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

三、常見註解簡介

 @Api：修飾整個類，描述Controller的作用
 @ApiOperation：描述一個類的一個方法，或者說一個介面
 @ApiParam：單個參數描述
 @ApiModel：用對象實體來作為入參
 @ApiProperty：用對象接實體收參數時，描述對象的一個欄位
 @ApiResponse：HTTP響應其中1個描述
 @ApiResponses：HTTP響應整體描述
 @ApiIgnore：使用該註解忽略這個API
 @ApiError ：發生錯誤返回的資訊
 @ApiImplicitParam：一個請求參數
 @ApiImplicitParams： 多個請求參數