Spring Boot3整合knife4j(swagger3)

⛰️个人主页:     蒾酒

🔥系列专栏：《spring boot实战》

---

目录

1.前置条件

2.导依赖

3.配置

---

1.前置条件

已经初始化好一个spring boot项目且版本为3X，项目可正常启动。

作者版本为3.2.2

初始化教程：

新版idea创建spring boot项目-CSDN博客https://blog.csdn.net/qq_62262918/article/details/135785412?spm=1001.2014.3001.5501

2.导依赖

knife4j官网：

Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j (xiaominfo.com)https://doc.xiaominfo.com/依赖选择：

作者的使用的spring boot 3.2.2为当前最新版，所以依赖导入最新的knife4j 4.4.0

pom.xml:

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

3.配置

官方文档（快速开始）：

快速开始 | Knife4j (xiaominfo.com)https://doc.xiaominfo.com/docs/quick-start

官方文档（详细配置）：

3.1 增强模式 | Knife4j (xiaominfo.com)https://doc.xiaominfo.com/docs/features/enhance

application.yml：

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: '蒾酒'
      paths-to-match: '/**'
      #生成文档所需的扫包路径，一般为启动类目录
      packages-to-scan: com.mijiu


#knife4j配置
knife4j:
  #是否启用增强设置
  enable: true
  #开启生产环境屏蔽
  production: false
  #是否启用登录认证
  basic:
    enable: true
    username: admin
    password: 123456
  setting:
    language: zh_cn
    enable-version: true
    enable-swagger-models: true
    swagger-model-name: 用户模块

写个接口：

@Tag注解：标记接口类别

@Operation:标记接口操作

@RestController
@Tag(name = "用户接口")
@RequestMapping("/user")

public class UserController {
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/list")
    @Operation(summary = "用户列表")
    public List<User> test(){
        return userService.list();
    }

    @Operation(summary = "你好")
    @GetMapping("/hello")
    public Object test2(){
        return "hello";
    }
}

启动项目：

浏览器输入：http://ip:port/doc.html

接口已经识别到了

接下来配置以下接口文档的作者等信息

在config目录下新建配置类：

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

/**
 * @author mijiupro
 */
@Configuration
public class Knife4jConfig {
    @Bean
    public OpenAPI springShopOpenApi() {
        return new OpenAPI()
                // 接口文档标题
                .info(new Info().title("蒾酒的demo")
                        // 接口文档简介
                        .description("这是基于Knife4j OpenApi3的测试接口文档")
                        // 接口文档版本
                        .version("1.0版本")
                        // 开发者联系方式
                        .contact(new Contact().name("蒾酒")
                                .email("000000000@qq.com")));
        
    }

}

重启项目，再次访问

每次都要打开浏览器输入地址访问不友好

启动类上优化：

@SpringBootApplication
@MapperScan("com.mijiu.mapper")
@Slf4j
public class SpringbootTemplateApplication {
    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(SpringbootTemplateApplication.class);
        Environment env = app.run(args).getEnvironment();
        app.setBannerMode(Banner.Mode.CONSOLE);
        logApplicationStartup(env);

    }
    private static void logApplicationStartup(Environment env) {
        String protocol = "http";
        if (env.getProperty("server.ssl.key-store") != null) {
            protocol = "https";
        }
        String serverPort = env.getProperty("server.port");
        String contextPath = env.getProperty("server.servlet.context-path");
        if (StringUtils.isBlank(contextPath)) {
            contextPath = "/doc.html";
        } else {
            contextPath = contextPath + "/doc.html";
        }
        String hostAddress = "localhost";
        try {
            hostAddress = InetAddress.getLocalHost().getHostAddress();
        } catch (UnknownHostException e) {
            log.warn("The host name could not be determined, using `localhost` as fallback");
        }
        log.info("""

                        ----------------------------------------------------------
                        \t应用程序“{}”正在运行中......
                        \t接口文档访问 URL:
                        \t本地: \t\t{}://localhost:{}{}
                        \t外部: \t{}://{}:{}{}
                        \t配置文件: \t{}
                        ----------------------------------------------------------""",
                env.getProperty("spring.application.name"),
                protocol,
                serverPort,
                contextPath,
                protocol,
                hostAddress,
                serverPort,
                contextPath,
                env.getActiveProfiles());
    }

}

效果如图：

点击直接跳转。

完成！