甩掉接口文档烦恼！Spring Boot 集成 Knife4j，轻松玩转 API 可视化

news2024/11/19 19:34:09

一、引言：跟接口文档说拜拜 👋

作为一名 Java 开发者，你是否还在为编写繁琐的 API 文档而头疼？传统的手动编写方式不仅耗时费力，而且容易出错，难以维护。今天，我们就来介绍一款神器 Knife4j，它可以帮助你轻松生成美观、易于使用的 API 文档，让你告别文档编写烦恼！

二、Knife4j 简介：API 文档界的“后起之秀”

简单来说，Knife4j 是一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案，它不仅拥有 Swagger 的所有功能，还做了很多优化和增强，例如：

界面更美观： 提供简洁美观的界面，方便用户浏览和使用 API 文档。
功能更丰富： 支持接口排序、搜索、分组等功能，支持多种格式输出。
易用性更高： 提供了更友好的配置方式，使用起来更加简单方便。

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

1. 添加依赖：引入 Knife4j 包

在你的 Spring Boot 项目的 pom.xml 文件中添加以下依赖：

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

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

创建一个配置类，例如 Knife4jConfiguration，使用 @EnableSwagger2WebMvc 注解开启 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
public class 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 的后台管理系统。")
                        .termsOfServiceUrl("https://doc.uyii.cn/")
                        .contact("zhy@uyii.cn")
                        .version("1.0")
                        .build())
                .select()
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

3. 运行项目：见证奇迹的时刻 ✨

启动你的 Spring Boot 应用，在浏览器中访问 http://localhost:8800/doc.html，你就能看到 Knife4j 生成的 API 文档啦！

四、进阶用法：玩转 Knife4j，定制你的 API 文档 🎨

分组管理 API 文档：

  @Bean
  public Docket adminApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .groupName("admin")
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.muqing.admin")) // 修改为你的模块包路径
              .paths(PathSelectors.any())
              .build();
  }

  @Bean
  public Docket frontApi() {
      return new 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) {
        // ...
    }
}

五、实战演练：小试牛刀，巩固学习成果 💪

我们来创建一个简单的 Spring Boot 项目，演示如何使用 Knife4j 生成 API 文档：

1. 创建一个 Spring Boot 项目，添加 Web 依赖和 Knife4j 依赖。

2. 创建一个 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 = "后台首页")
@RequestMapping("/front")
public class FrontIndexController {

    @Autowired
    private FrontIndexService frontIndexService;

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

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