快捷導(dǎo)航

SpringBoot整合knife4j3.0.3實現(xiàn)過程

更新時間：2026年01月08日 14:34:41 作者：jpq+

文章介紹了如何在SpringBoot項目中使用Swagger和Knife4j來生成和增強(qiáng)API文檔,Swagger通過注解自動生成API文檔,而Knife4j則提供了更豐富的功能,如在線調(diào)試、多語言支持和離線文檔導(dǎo)出等,通過配置和使用這些工具,可以提高API文檔的管理和使用效率

配置

pom.xml:

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

Swagger使用

在Spring Boot項目中，Controller通常會有多個接口，我們可以通過在Controller類上添加@Api注解來為API接口添加描述信息，以及使用@ApiOperation注解來為單個接口添加描述信息。

使用

在Spring Boot項目中，我們可以通過Swagger注解@Api來定義接口分組。@Api注解指定了該Controller的標(biāo)簽為“用戶管理”，這個標(biāo)簽將作為接口分組的名稱：：

@RestController
@RequestMapping("/users")
@Api(tags = "用戶管理")
public class UserApi {
   
}

當(dāng)一個Controller包含多個接口時，可以通過@ApiOperation注解指定每個接口的簡介和說明。例如：

@RestController
@RequestMapping("/users")
@Api(tags = "用戶管理")
public class UserApi {

    @GetMapping("/{id}")
    @ApiOperation(value = "獲取用戶信息", notes = "根據(jù)用戶ID獲取用戶信息")
    public User getUserById(@PathVariable("id") Long id) {
       
    }

    @PostMapping
    @ApiOperation(value = "創(chuàng)建用戶", notes = "創(chuàng)建新用戶")
    public User createUser(@RequestBody User user) {
       
    }

    // ...
}

此外，設(shè)置項目的基本信息也是有必要的。

@EnableOpenApi
@Configuration
public class DocumentConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jp"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("管理平臺API文檔")
                .description("管理系統(tǒng)")
                .contact(new Contact("jp", "", ""))
                .version("2.0.0")
                .build();
    }
}

打開API文檔地址：

接口字段說明

Swagger提供了@ApiImplicitParam注解。

下面演示使用@ApiImplicitParam注解指定了每個參數(shù)的名稱、類型和說明：

@RestController
@RequestMapping("/users")
@Api(tags = "用戶管理")
public class UserApi {

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

    @PostMapping
    @ApiOperation(value = "創(chuàng)建用戶", notes = "創(chuàng)建新用戶")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "user", value = "用戶實體", required = true, dataType = "User", paramType = "body")
    })
    public User createUser(@RequestBody User user) {
        // ...
    }

    // ...
}

Knife4j 增強(qiáng)功能

離線文檔導(dǎo)出： 用戶可以直接在界面上導(dǎo)出 HTML、Markdown 或 Word 格式的離線文檔，這對于沒有網(wǎng)絡(luò)環(huán)境下的開發(fā)、分享或者存檔非常有用。
接口排序與分組： Knife4j 支持對API接口進(jìn)行自定義排序和分組，使得文檔結(jié)構(gòu)更加清晰有序，方便用戶快速定位到所需接口。
在線調(diào)試與數(shù)據(jù)模擬： 除了基本的接口調(diào)用測試外，Knife4j 還增強(qiáng)了在線調(diào)試功能，支持設(shè)置請求頭、Cookie、Body等多種參數(shù)，以及保存歷史請求、導(dǎo)入導(dǎo)出測試數(shù)據(jù)等，便于開發(fā)者快速驗證API功能。
登錄認(rèn)證支持： 為了保護(hù)API文檔的安全，Knife4j 支持多種登錄認(rèn)證方式（如Basic Auth、OAuth2等），可以對接企業(yè)的統(tǒng)一認(rèn)證系統(tǒng)，確保只有授權(quán)用戶才能訪問API文檔。
國際化支持： 內(nèi)置多語言支持，可以根據(jù)用戶瀏覽器的語言偏好自動切換界面語言，提高國際團(tuán)隊的協(xié)作效率。