首頁 > 軟體

Java Swagger使用教學

2022-07-19 14:03:13

Swagger簡介

為什麼使用Swagger

  這個問題就牽涉到技術的更新迭代了,在之前的後端時代,前端只需要管理靜態頁面,而後端需要使用模板引擎(JSP等)去得資料並加以處理,最後顯示出資料。但是隨著時代的發展,開發慢慢進入了前後端分離的時代,前端和後端分成了兩個相對獨立的團隊來合作開發,這就造成了一個問題:前後端整合聯調的時候,前後端人員無法做到“及時協商,儘早解決”,最終造成問題的集中爆發。

  既然已經發現問題,那麼就需要使用一種解決方案來避免這個問題的干擾。做過一個完整專案的小夥伴應該都有所瞭解,前後端之間的共同作業基本上都在api介面和資料傳輸上,那麼如果api介面能夠統一、資料的格式能夠一致,那麼問題也就迎刃而解了。

  於是Swagger應運而生,Swagger可以根據在程式碼中使用自定義的註解來生成介面檔案,這樣做的好處是在開發介面時可以通過swagger將介面檔案定義好,方便前後端團隊之間的共同作業,同時也方便以後的維護。

Swagger的設定

Spring boot整合Swagger

新建一個spring boot專案

匯入兩個依賴

<!--Swagger(開始)-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!--Swagger(結束)-->

設定Swagger

@Configuration
@EnableSwagger2     // 開啟Swagger2
public class SwaggerConfig {
}

  如果只是使用設定類開啟Swagger的話,它的底層會有一些DEFAULT(預設)的值,開啟之後就可以使用網址http://localhost:8080/swagger-ui.html來存取這個Swagger的檔案介面。

  

當然,既然有預設的設定,我們就可以實現客製化化的設定覆蓋,依然是在這個設定類中進行修改

@Configuration
@EnableSwagger2     // 開啟Swagger2
public class SwaggerConfig {
    /**
     *用於客製化化設定Docket的bean範例
     */
    @Bean
    public Docket Docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(ApiInfo());
    }
    /**
     * 客製化化資訊的主要設定處
     */
    private ApiInfo ApiInfo() {
        // 作者的個人資訊
        Contact contact = new Contact("作者的姓名", "作者的個人社交主頁", "作者的郵箱");
        return new ApiInfo(
                "標題:Swagger的測試介面檔案",
                "簡介:這是一段簡介,關於介面檔案的簡介",
                "版本號:1.0",
                "網頁:這是一個網頁連結",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }
}

  修改之後的頁面資訊就會有一些不一樣,restart專案之後重新存取ui介面

設定Swagger可掃描的介面

  這一部分的工作也是在SwaggerConfig設定類中實現,主要就是設定哪些api介面會被Swagger生成介面檔案,生成檔案的api就會在swagger的ui介面上顯示。通過以下.apis和.paths的設定,達到的效果就是之後在com.xiaochen.swagger.controller包下的且對映路徑為/hello的才會生成對應的介面檔案

 @Bean
public Docket Docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            /**
             * apis就是設定哪些api可以被掃描
             * 主要引數可以包括:
             *  - RequestHandlerSelectors.basePackage():指定可以掃描的包 引數是包(package)名
             *  - RequestHandlerSelectors.any():掃描所有
             *  - RequestHandlerSelectors.none():都不掃描
             *  - RequestHandlerSelectors.withClassAnnotation():掃描類上註解  引數是註解類的反射物件,eg:@RestController.class
             *  - RequestHandlerSelectors.withMethodAnnotation()掃描方法上註解  引數是註解類的反射物件,eg:@RequestMapping.class
             */
            .apis(RequestHandlerSelectors.basePackage("com.xiaochen.swagger.controller"))
            /**
             * paths就是設定哪些對映路徑下的api可以被掃描
             * 主要引數可以包括:
             *  - PathSelectors.ant():指定對映路徑 主要就是斜槓+單詞或者萬用字元
             *  - PathSelectors.any():掃描所有
             *  - PathSelectors.none():都不掃描
             *  - PathSelectors.regex():掃描符合正則的所有路徑
             */
            .paths(PathSelectors.ant("/hello"))
            .build()
            .apiInfo(ApiInfo());
}

控制Swagger的開關

  使用.enable可以控制Swagger的開關,如果關閉了Swagger的話就會導致ui介面無法開啟,也就無法檢視介面檔案

  

那麼該如何實現只在開發和測試階段開啟Swagger呢?首先應該先預設一下想要開啟的專案環境,通過Environment 物件來監聽專案的環境與預設的是否一致,最後使用.enable控制Swagger的開關

@Bean
public Docket Docket(Environment environment) {
    // 預設的專案環境(可設定多個)
    Profiles profiles = Profiles.of("dev", "test");
    // 監聽專案的環境與預設的是否一致
    boolean flag = environment.acceptsProfiles(profiles);
    return new Docket(DocumentationType.SWAGGER_2)
            .enable(flag);
}

設定Swagger的分組

  在沒有設定Swagger的分組之前,有一個預設的default分組,分組個數的多少就取決於SwaggerConfig 設定類中有多少個Docket 範例,值得注意的是:不能出現同名的分組,即使是未命名的分組(也就是default)也不能重複出現,否則就會報java.lang.IllegalStateException異常

Swagger的各種註釋

controller層使用到的註解

  • @ApiOperation(“註釋”):加在方法上,註釋這個方法
  • @ApiParam(“註釋”):加在引數前,註釋這個引數

entity層使用到的註解

  • @ApiModel(“註釋”):加在實體類上,註釋整個實體類
  • @ApiModelProperty(“註釋”):加在實體類欄位上,註釋這個欄位

  model裡面是否有這個實體類,並不是取決於是否使用了哪個註解,而是方法的返回值是否包含這個實體類物件,也就是看有沒有一個方法return了這個物件。

使用Swagger介面測試

這裡的使用和postman幾乎一樣,可以借鑑學習

到此這篇關於Java Swagger使用教學的文章就介紹到這了,更多相關Java Swagger內容請搜尋it145.com以前的文章或繼續瀏覽下面的相關文章希望大家以後多多支援it145.com!


IT145.com E-mail:sddin#qq.com