Knife4j Gateway使用詳解

Knife4j Gateway是一款開源、免費的API文檔管理工具，基於SpringBoot2.x、Swagger2、Bootstrap、Vue.js等技術實現，提供了前後端完全分離的方式來展示API文檔，使開發人員能夠輕鬆地創建、維護和分享API文檔。本文將從多個方面對Knife4j Gateway進行詳細的闡述。

一、快速上手

1、引入依賴


<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.2</version>
</dependency>

2、在配置文件中進行配置


# Knife4j配置信息
knife4j:
  # Swagger-API文檔基礎信息配置
  api-docs:
    groupName: xxx項目API文檔
    apiBasePackage: 導入項目中需要生成文檔的介面基礎包名
    title: xxx API介面文檔
    description: xxx介面文檔描述信息
    contact:
      name: xxxx
      email: xxxx
      url: "xxx"
    version: 1.0.0
    license:
      name: xxxx
      url: xxxx
    termsOfServiceUrl: xxxx
    host: xxxx
  # GatewayAPI配置信息
  gateway:
    globalLatencyTiming: true

3、創建介面文檔類


@RestController
@Api(tags = "測試介面管理")
@RequestMapping("/test")
public class TestController {

    @ApiOperation(value = "測試API", notes = "測試API")
    @ApiResponses({@ApiResponse(code = 200, message = "操作成功", response = String.class)})
    @GetMapping(value = "/echo/{string}", produces = MediaType.APPLICATION_JSON_VALUE)
    public String echo(@PathVariable String string) {
        return "echo:" + string;
    }

}

4、啟動項目，訪問http://localhost:port/doc.html即可查看API文檔頁面。

二、功能詳細介紹

1、基本信息配置

在Knife4j Gateway中，可以通過配置文件進行基本信息的配置，或者通過Java註解進行詳細的配置。


@Api(tags = {"用戶信息管理"})
@ApiInfo(value = "用戶信息管理", description = "用戶信息管理API介面文檔")
@RestController
@RequestMapping(value = "/user")
public class UserController {

    @ApiOperation(value = "根據ID獲取用戶信息", notes = "獲取指定ID的用戶信息")
    @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }

}

2、介面說明

在Knife4j Gateway中，使用@Api註解來標記介面說明信息。


@Api(tags = {"用戶信息管理"})
public interface UserService {

    @ApiOperation(value = "獲取所有用戶信息", notes = "獲取所有用戶信息")
    List listAllUser();

}

3、參數說明

在Knife4j Gateway中，使用@ApiImplicitParam註解來標記參數說明信息。


@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long", paramType = "path")
@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.getUserById(id);
}

4、返回值說明

在Knife4j Gateway中，使用@ApiResponse註解來標記返回值說明信息。


@ApiResponses({@ApiResponse(code = 200, message = "操作成功", response = String.class)})
@GetMapping(value = "/hello")
public String sayHello() {
    return "Hello World!";
}

5、分組管理

在Knife4j Gateway中，可以通過分組管理來區分不同的API介面，方便API介面的管理和查找。


@Api(tags = {"用戶信息管理"})
public interface UserService {

    @ApiOperation(value = "獲取所有用戶信息", notes = "獲取所有用戶信息")
    List listAllUser();

}

@Api(tags = {"訂單信息管理"})
public interface OrderService {

    @ApiOperation(value = "獲取所有訂單信息", notes = "獲取所有訂單信息")
    List listAllOrder();

}

三、常用擴展

1、集成Swagger-Bootstrap-UI

Swagger-Bootstrap-UI是一款基於Swagger2的API文檔UI增強工具，可以幫助API文檔頁面展示的更加美觀和易於使用。通過在Knife4j Gateway中引入Swagger-Bootstrap-UI，可以讓API文檔頁面擁有更加豐富的功能。

引入Swagger-Bootstrap-UI的依賴：


<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.4</version>
</dependency>

在配置文件中啟用Swagger-Bootstrap-UI：


# Swagger-Bootstrap-UI配置信息
swagger:
  base-package: 掃描項目中需要生成文檔的介面基礎包名
  contact:
    name: 某某公司
  title: 項目名稱 - API介面文檔
  description: 項目描述信息
  enable: true
  version: 1.0.0
  termsOfServiceUrl: http://xxxx
  authorization:
    name: Authorization
    description: 在請求頭中添加Token信息，格式為"Bearer token"

2、API文檔訪問控制

在一些敏感的項目中，需要對API文檔的訪問進行控制，防止未授權的人員訪問API文檔。Knife4j Gateway提供了訪問控制的方式，使用Spring Security進行安全控制。

添加Spring Security的依賴：


<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

配置Spring Security：


@Configuration
@EnableWebSecurity
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .authorizeRequests()
                .antMatchers("/doc.html", "/webjars/**", "/v2/api-docs", "/swagger-resources/**")
                .permitAll()
                .anyRequest()
                .authenticated()
                .and()
                .formLogin()
                .loginPage("/login.html")
                .permitAll()
                .and()
                .logout()
                .permitAll();
    }

    @Override
    public void configure(WebSecurity web) throws Exception {
        web.ignoring().antMatchers("/css/**", "/js/**", "/webjars/**");
    }
}

3、介面文檔自定義UI

在Knife4j Gateway中，默認使用了Bootstrap-Vue作為UI框架，但是開發人員可以根據自己的需求進行UI的自定義，以便更好的滿足業務需求。

在resources/templates目錄下創建自定義的HTML模板，使用FreeMarker或Thymeleaf等模板引擎來渲染頁面，然後在配置文件中進行UI的配置即可。


# UI配置信息
knife4j:
  ui:
    isDefault: false # 是否使用默認UI
    url: /doc.html # 訪問API文檔的URL
    title: 項目名稱API介面文檔 # 頁面標題
    logo: /static/images/logo.png # Logo圖片地址
    tagsSorter: alpha # 標籤排序方式：alpha/alphabetical/alphaDesc
    operationsSorter: method # 操作排序方式：method/methodDesc/path/pathDesc
    disableFilter: false # 是否禁用過濾功能
    enableSwaggerBootstrapUi: true # 是否啟用Swagger-Bootstrap-UI
    apiDocsUrl: /v2/api-docs # 獲取API文檔信息的URL
    footer:
      name: xxx公司 # 版權信息
      url: http://xxxx # 鏈接地址

四、常見問題

1、如何在Knife4j Gateway中使用全局異常處理？

Knife4j Gateway默認使用SpringBoot的全局異常處理，但是在一些特殊的業務場景中，可能需要自定義全局異常處理。可以通過@ControllerAdvice註解來實現的全局異常處理。


@ControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 處理異常：NullPointerException
     *
     * @param e NullPointerException異常
     * @return 錯誤信息
     */
    @ExceptionHandler(value = {NullPointerException.class})
    public ResponseEntity handleNullPointerExceptionException(Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("系統繁忙！");
    }

}

2、如何為Knife4j Gateway中的介面設置訪問限制？

為了保護系統的安全和穩定，可能需要為Knife4j Gateway中的介面設置訪問限制。可以通過使用Spring Security等安全框架來為介面設置訪問限制。

3、如何將Knife4j Gateway中的API文檔集成到SwaggerHub中？

可以使用SwaggerHub提供的導入功能，將Knife4j Gateway中的API文檔導入到SwaggerHub中進行管理。

在SwaggerHub中，選擇「APIs」菜單，然後在「New API」下拉菜單中選擇「Import API」，在彈出的窗口中選擇「Import from Remote URL」，輸入Knife4j Gateway中API文檔的URL，然後點擊「Import API」按鈕完成導入。

五、總結

通過本文的介紹，不難看出Knife4j Gateway具有許多豐富的功能和優秀的易用性，對於開發人員來說是一款非常實用和優秀的API文檔管理工具。使用Knife4j Gateway可以讓開發人員輕鬆地創建、維護和分享API文檔，從而提高項目的效率和可維護性。

原創文章，作者：VFXWN，如若轉載，請註明出處：https://www.506064.com/zh-tw/n/334780.html