什么是 Knife4j

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

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

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

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

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

在 Maven 項(xiàng)目中，添加 Knife4j 的核心依賴：

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

在config層中創(chuàng)建一個(gè)配置類來(lái)配置 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 項(xiàng)目中的支持，Docket 的配置與原生 Swagger 類似，用于指定要掃描的 API 接口范圍和基本的文檔信息，通過(guò)RequestHandlerSelectors.basePackage  確定了需要生成文檔的 Controller 所在的包路徑， PathSelectors.any()  表示包含所有的 API 路徑。

啟動(dòng)項(xiàng)目查看 Knife4j UI

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

圖示如下：

API 信息定制

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

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

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

再次啟動(dòng)項(xiàng)目查看：

成功顯示更改信息。

總結(jié)

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

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

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

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

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

最新評(píng)論