什么是 Knife4j

Knife4j 是為Java MVC 框架（如Spring Boot、Spring MVC等）集成 Swagger 生成 API 文檔的增強解決方案，它基于 Swagger 的核心功能，通過定制化的前端界面和一些額外的特性，擁有比原生 Swagger UI 更美觀、直觀的操作界面。

Knife4j支持離線文檔下載，方便在沒有網(wǎng)絡(luò)連接的情況下查閱 API 文檔，擁有接口排序功能，使得 API 文檔的結(jié)構(gòu)更加清晰有序，也具備動態(tài)參數(shù)調(diào)試能力，能夠?qū)崟r修改請求參數(shù)并查看響應(yīng)結(jié)果，方便開發(fā)過程中的接口測試。

在Spring中集成 Knife4j 的準(zhǔn)備工作

搭建好一個基于Spring的項目環(huán)境，可以是 Spring Boot 項目或者傳統(tǒng)的 Spring MVC 項目，以 Spring Boot 項目為例，首先需要在 pom.xml 文件中引入必要的 Spring Web 相關(guān)依賴：

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

在 Maven 項目中，添加 Knife4j 的核心依賴：

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

在config層中創(chuàng)建一個配置類來配置 Knife4j：

@Configuration
@EnableKnife4j
public class Knife4jConfig {
 
    @Bean
    public Docket docket() {
        return new Docket(DocumentationPlugin.DEFAULT_GROUP_NAME)
              .apiInfo(apiInfo())
              .select()
              .apis(RequestHandlerSelectors.basePackage("http://Controller包路徑")) 
              .paths(PathSelectors.any())
              .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
              .title("我的接口文檔")
              .description("我的接口文檔")
              .version("2.0")
              .build();
    }
}

在上述代碼中 @EnableKnife4j  注解開啟了 Knife4j 在 Spring 項目中的支持，Docket 的配置與原生 Swagger 類似，用于指定要掃描的 API 接口范圍和基本的文檔信息，通過RequestHandlerSelectors.basePackage  確定了需要生成文檔的 Controller 所在的包路徑， PathSelectors.any()  表示包含所有的 API 路徑。

啟動項目查看 Knife4j UI

啟動 Spring 項目后，訪問http://localhost:8080/doc.html （默認(rèn)端口為 8080，如果項目中配置了其他端口則相應(yīng)替換），即可打開 Knife4j 的界面。在這個界面上，可以看到項目中所有被掃描到的 API 接口信息，包括接口名稱、請求方法、請求參數(shù)、響應(yīng)示例等，相比原生的Swagger UI，界面更加美觀和易于操作，例如接口列表的展示更加清晰，搜索功能更加便捷等。

圖示如下：

API 信息定制

在 Spring 的 Controller 類及方法中，使用Knife4j支持的 Swagger 注解來詳細(xì)描述 API，例如：

@RestController
@RequestMapping("/api")
@Api(tags = "我的api")
public class UserController {
 
    @GetMapping("/users")
    @ApiOperation("用戶列表")
    public List<User> getUsers() {
        // 實際業(yè)務(wù)邏輯代碼，這里返回用戶列表
        return userService.getUsers();
    }
}

• @Api 注解為整個 Controller 類添加一個標(biāo)簽，方便在 Knife4j UI 中對接口進行分類查看。
• @ApiOperation  注解詳細(xì)描述了每個 API 方法的功能，該描述會在 Knife4j 界面中對應(yīng)接口的詳情頁中展示，讓使用者能夠快速了解接口的用途。

再次啟動項目查看：

成功顯示更改信息。

總結(jié)

除了基礎(chǔ)的配置和使用，還能通過以下方式擴展 Knife4j 的應(yīng)用，在復(fù)雜的微服務(wù)架構(gòu)中，利用其分組功能，為不同的微服務(wù)模塊創(chuàng)建獨立的 Docket  實例并設(shè)置不同 groupName ，使各模塊 API 文檔清晰區(qū)分，方便維護和查看。

對于 API 版本管理，除了在 URL 中體現(xiàn)版本，還可以結(jié)合自定義請求頭，在 Knife4j 配置中精準(zhǔn)匹配不同版本的接口路徑，展示版本演進。

在安全方面，與多種認(rèn)證方式深度集成，如 OAuth2 等，通過詳細(xì)配置 securitySchemes  和 securityContexts ，在 API 文檔中準(zhǔn)確呈現(xiàn)復(fù)雜的認(rèn)證流程和要求，幫助使用者更好地理解和接入安全的 API 服務(wù)。

總之，掌握在Spring中使用Knife4j的基本使用，能夠高效地為項目生成友好且實用的API文檔，提升整個項目開發(fā)過程中的溝通協(xié)作效率以及接口管理的便利性。

以上就是在Spring中使用Knife4j進行API文檔生成與管理的操作方法的詳細(xì)內(nèi)容，更多關(guān)于Spring API文檔生成與管理的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論