甩掉接口文檔煩惱！Spring Boot 集成 Knife4j，輕松玩轉(zhuǎn) API 可視化

作者：張慧源 2025-02-12 07:13:54

今天，我們就來(lái)介紹一款神器 Knife4j，它可以幫助你輕松生成美觀、易于使用的 API 文檔，讓你告別文檔編寫煩惱！

一、引言：跟接口文檔說(shuō)拜拜

作為一名 Java 開(kāi)發(fā)者，你是否還在為編寫繁瑣的 API 文檔而頭疼？傳統(tǒng)的手動(dòng)編寫方式不僅耗時(shí)費(fèi)力，而且容易出錯(cuò)，難以維護(hù)。今天，我們就來(lái)介紹一款神器 Knife4j，它可以幫助你輕松生成美觀、易于使用的 API 文檔，讓你告別文檔編寫煩惱！

二、Knife4j 簡(jiǎn)介：API 文檔界的“后起之秀”

簡(jiǎn)單來(lái)說(shuō)，Knife4j 是一個(gè)集 Swagger2 和 OpenAPI3 為一體的增強(qiáng)解決方案，它不僅擁有 Swagger 的所有功能，還做了很多優(yōu)化和增強(qiáng)，例如：

界面更美觀：提供簡(jiǎn)潔美觀的界面，方便用戶瀏覽和使用 API 文檔。
功能更豐富：支持接口排序、搜索、分組等功能，支持多種格式輸出。
易用性更高：提供了更友好的配置方式，使用起來(lái)更加簡(jiǎn)單方便。

三、Spring Boot 集成 Knife4j：三步搞定，輕松上手

1. 添加依賴：引入 Knife4j 包

在你的 Spring Boot 項(xiàng)目的 pom.xml 文件中添加以下依賴：

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

2. 配置 Knife4j：告訴它你的 API 信息

創(chuàng)建一個(gè)配置類，例如 Knife4jConfiguration，使用 @EnableSwagger2WebMvc 注解開(kāi)啟 Swagger 功能，并配置 Docket Bean，就像這樣：

package com.muqing.common.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
publicclass Knife4jConfiguration {
    @Bean(value = "mq-admin-api")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("MQ-ADMIN API文檔")
                        .description("# 基于 Spring Boot 與 Vue3 的后臺(tái)管理系統(tǒng)。")
                        .termsOfServiceUrl("https://doc.uyii.cn/")
                        .contact("zhy@uyii.cn")
                        .version("1.0")
                        .build())
                .select()
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

3. 運(yùn)行項(xiàng)目：見(jiàn)證奇跡的時(shí)刻

啟動(dòng)你的 Spring Boot 應(yīng)用，在瀏覽器中訪問(wèn) http://localhost:8800/doc.html，你就能看到 Knife4j 生成的 API 文檔啦！

四、進(jìn)階用法：玩轉(zhuǎn) Knife4j，定制你的 API 文檔

分組管理 API 文檔：

@Bean
public Docket adminApi() {
      returnnew Docket(DocumentationType.SWAGGER_2)
              .groupName("admin")
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.muqing.admin")) // 修改為你的模塊包路徑
              .paths(PathSelectors.any())
              .build();
  }

@Bean
public Docket frontApi() {
      returnnew Docket(DocumentationType.SWAGGER_2)
              .groupName("front")
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.muqing.front")) // 修改為你的模塊包路徑
              .paths(PathSelectors.any())
              .build();
  }

自定義 API 信息：

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

    @GetMapping("/{id}")
    @ApiOperation("獲取用戶信息")
    public User getUser(@PathVariable Long id) {
        // ...
    }
}

五、實(shí)戰(zhàn)演練：小試牛刀，鞏固學(xué)習(xí)成果

我們來(lái)創(chuàng)建一個(gè)簡(jiǎn)單的 Spring Boot 項(xiàng)目，演示如何使用 Knife4j 生成 API 文檔：

創(chuàng)建一個(gè) Spring Boot 項(xiàng)目，添加 Web 依賴和 Knife4j 依賴。
創(chuàng)建一個(gè) FrontIndexController，編寫接口：

package com.muqing.front.controller;

import com.muqing.common.api.ApiResult;
import com.muqing.front.entity.Article;
import com.muqing.front.service.FrontIndexService;
import com.muqing.front.vo.IndexVo;
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * IndexController
 *
 * @author zhy
 * @since 2023/6/5
 */
@RestController
@Api(tags = "后臺(tái)首頁(yè)")
@RequestMapping("/front")
publicclass FrontIndexController {

    @Autowired
    private FrontIndexService frontIndexService;

    /**
     * 首頁(yè)博主信息
     *
     * @return {@link ApiResult}<{@link IndexVo}>
     */
    @ApiOperation("博主信息")
    @GetMapping()
    public ApiResult<IndexVo> index() {
        IndexVo IndexVo = frontIndexService.getAuthorInfo();
        return ApiResult.success(IndexVo);
    }

    /**
     * 關(guān)于我
     *
     * @return {@link Article}
     */
    @ApiOperation("關(guān)于我")
    @GetMapping("/about")
    public ApiResult<Article> about() {
        Article article = frontIndexService.getAbout();
        return ApiResult.success(article);
    }
}

運(yùn)行項(xiàng)目，訪問(wèn) http://localhost:8080/doc.html，查看生成的 API 文檔。

結(jié)語(yǔ)：API 文檔，從此輕松搞定

Knife4j 為我們提供了一種簡(jiǎn)單高效的方式來(lái)生成和管理 API 文檔，從此告別繁瑣的手動(dòng)編寫，讓前后端協(xié)作更加順暢！希望這篇文章能夠幫助你快速上手 Knife4j，更多進(jìn)階的技能請(qǐng)閱讀官方文檔！

責(zé)任編輯：趙寧寧來(lái)源：源話編程