Springboot3集成knife4j，swagger实现在线接口文档

什么是knife4j

knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案，帮助开发者快速聚合使用OpenAPI规范，快速生成API文档，并且提供一些额外的功能，比如:

1. API文档生成：可以根据Controller和方法上的注解自动生成Markdown格式的API文档
2. 在线访问API：可以在knife4j的页面直接访问我们的API接口
3. Token管理：可以在knife4j中对API Token进行管理
4. 比较请求与响应：可以比较同一个API的请求与响应内容的差异
5. 高亮API响应：将API响应中的JSON高亮显示，方便查看
6. ......具体信息请看官网文档

knife4j官网：https://doc.xiaominfo.com/

我以之前那篇集成邮箱的笔记为基础集成 knife4j，有不懂邮箱验证的可以去看我的笔记

Springboot集成邮箱发送验证码-CSDN博客

1 引入依赖

这里我直接把我项目的所有依赖放出来了

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

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

        <!-- 邮箱验证码依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-mail</artifactId>
        </dependency>
        <!-- 一个很强大的工具库 -->
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>5.8.19</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--swagger测试-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.1.0</version>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

    </dependencies>

2 yaml文件配置

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.example.email.controller #这里要选择你的接口对应的包名
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

 3 knife4j 配置类

package com.example.email.config;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("邮箱验证码接口文档")
                        .description("邮箱验证码接口文档")
                        .version("v1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("外部文档")
                        .url("https://springshop.wiki.github.org/docs"));
    }
    
}

4 编写测试接口

首先项目的目录结构是这样的

 测试接口代码如下：

package com.example.email.controller;

import cn.hutool.core.util.RandomUtil;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.mail.SimpleMailMessage;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/send")
@RequiredArgsConstructor //Lombook提供的构造，使用构造器注入bean
@Tag(name = "邮箱管理")
public class SendController {
    
    // 这个是 mail 依赖提供给我们的发送邮件的接口
    private final JavaMailSender mailSender;
    
    // yaml配置中获取发件人邮箱
    @Value("${spring.mail.username}")
    private String sender;
    
    // yaml配置中获取发件人昵称
    @Value("${spring.mail.nickname}")
    private String nickname;
    
    @GetMapping
    @Operation(summary = "发送")
    public String sendEmail(@Parameter(name = "email", description = "邮箱账号")String email){
        SimpleMailMessage message = new SimpleMailMessage();
        message.setFrom(nickname + '<' + sender + '>');
        message.setTo(email);
        message.setSubject("邮箱登录验证码");
        // 使用 hutool-all 生成 6 位随机数验证码
        String code = RandomUtil.randomNumbers(6);
        String content = "【验证码】您的验证码为：" + code + " 。 验证码五分钟内有效，逾期作废。";
        message.setText(content);
        mailSender.send(message);
        return "发送成功";
    }


}

5 运行项目

访问地址：http://localhost:8080/doc.html

效果如下：

点击 接口进行测试就OK啦

发送，发送验证码成功!