後端整合 Swagger + Knife4j 介面文件

柒墨轩發表於2024-11-05
後端Swagger

什麼是介面文件？寫介面資訊的文件，每條介面包括：

  • 請求引數
  • 響應引數
    • 錯誤碼
  • 介面地址
  • 介面名稱
  • 請求型別
  • 請求格式
  • 備註

who 誰用？一般是後端或者負責人來提供，後端和前端都要使用

為什麼需要介面文件？

  • 有個書面內容（背書或者歸檔），便於大家參考和查閱，便於 沉澱和維護 ，拒絕口口相傳
  • 介面文件便於前端和後端開發對接，前後端聯調的 介質 。後端 => 介面文件 <= 前端
  • 好的介面文件支援線上除錯、線上測試，可以作為工具提高我們的開發測試效率

怎麼做介面文件？

  • 手寫（比如騰訊文件、Markdown 筆記）
  • 自動化介面文件生成：自動根據專案程式碼生成完整的文件或線上除錯的網頁。Swagger，Postman（側重介面管理）（國外）；apifox、apipost、eolink（國產）

介面文件有哪些技巧？

Swagger 原理：

  1. 引入依賴（Swagger 或 Knife4j：https://doc.xiaominfo.com/knife4j/documentation/get_start.html）
  2. 自定義 Swagger 配置類
  3. 定義需要生成介面文件的程式碼位置（Controller）
  4. 千萬注意：線上環境不要把介面暴露出去！！！可以透過在 SwaggerConfig 配置檔案開頭加上 @Profile({"dev", "test"}) 限定配置僅在部分環境開啟
  5. 啟動即可
  6. 可以透過在 controller 方法上新增 @Api、@ApiImplicitParam(name = "name",value = "姓名",required = true) @ApiOperation(value = "向客人問好") 等註解來自定義生成的介面描述資訊

如果 springboot version >= 2.6，需要新增如下配置：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

swagger

1.匯入依賴

      <!-- 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>

2.新建config檔案

package com.xiao.usercenter.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;

/**
 * @author: lingqi
 * @date: 2024/11/05
 * @ClassName: yupao-backend01
 * @Description: 自定義 Swagger 介面文件的配置
 */
@Configuration // 配置類
@EnableSwagger2 // 開啟 swagger2 的自動配置
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        // 建立一個 swagger 的 bean 例項
        return new Docket(DocumentationType.SWAGGER_2)

                // 配置介面資訊
                .select() // 設定掃描介面
                // 配置如何掃描介面
                .apis(RequestHandlerSelectors
                                //.any() // 掃描全部的介面，預設
                                //.none() // 全部不掃描
                                .basePackage("com.xiao.usercenter.controller") // 掃描指定包下的介面，最為常用
                        //.withClassAnnotation(RestController.class) // 掃描帶有指定註解的類下所有介面
                        //.withMethodAnnotation(PostMapping.class) // 掃描帶有隻當註解的方法介面

                )
                .paths(PathSelectors
                                .any() // 滿足條件的路徑，該斷言總為true
                        //.none() // 不滿足條件的路徑，該斷言總為false（可用於生成環境遮蔽 swagger）
                        //.ant("/user/**") // 滿足字串表示式路徑
                        //.regex("") // 符合正則的路徑
                )
                .build();
    }
    
    // 基本資訊設定
    private ApiInfo apiInfo() {
        Contact contact = new Contact(
                "lingqi", // 作者姓名
                "https://www.cnblogs.com/qimoxuan", // 作者網址
                "2813930556@qq.com"); // 作者郵箱
        return new ApiInfoBuilder()
                .title("魚泡夥伴匹配系統-介面文件") // 標題
                .description("眾裡尋他千百度，慕然回首那人卻在燈火闌珊處") // 描述
                .termsOfServiceUrl("https://www.cnblogs.com/qimoxuan") // 跳轉連線
                .version("1.0") // 版本
                .license("Swagger-的使用(詳細教程)")
                .licenseUrl("https://www.cnblogs.com/qimoxuan")
                .contact(contact)
                .build();
    }

}

注意，如果springboot 版本>= 2.6，需要新增yml配置即可

3.直接啟動，訪問http://localhost:8080/api/swagger-ui.html

Knife4j

1.匯入依賴

        <!-- knife4j 介面文件 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.7</version>
        </dependency>

2.新建 SwaggerConfig檔案

package com.xiao.usercenter.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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.EnableSwagger2WebMvc;

/**
 * @author: lingqi
 * @date: 2024/11/05
 * @ClassName: yupao-backend01
 * @Description: 自定義 Swagger 介面文件的配置
 */
@Configuration
@EnableSwagger2WebMvc
@Profile({"dev", "test"})   //版本控制訪問
public class SwaggerConfig {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 這裡一定要標註你控制器的位置
                .apis(RequestHandlerSelectors.basePackage("com.xiao.usercenter.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * api 資訊
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("零柒使用者中心")
                .description("零柒使用者中心介面文件")
                .termsOfServiceUrl("https://www.cnblogs.com/qimoxuan")
                .contact(new Contact("lingqi","https://www.cnblogs.com/qimoxuan","2813930556@qq.com"))
                .version("1.0")
                .build();
    }
}
依然是注意yml檔案的配置。
3.直接啟動，訪問http://localhost:8080/api/doc.html

相關文章