Spring Boot 3.0 集成 knife4j 接口文档

admin管理员组

文章数量:1794759

Spring Boot 3.0 集成 knife4j 接口文档

1、环境

Java: 21
Spring Boot: 3.3.4
Maven: 3.9.9

2、实操

2.1 引入依赖

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

2.2 添加配置文件

package com.jie.springbootinit.config;

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.springdoc.core.customizers.GlobalOpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.Map;

/**
 * Knife4j配置
 * 
 * @author jie
 */
@Configuration
public class SwaggerConfig {
    /**
     * API标题
     */
    private static final String API_TITLE = "Jie的API";
    /**
     * API版本
     */
    private static final String API_VERSION = "1.0";
    /**
     * API描述
     */
    private static final String API_DESCRIPTION = "Knife4j集成springdoc-openapi示例";
    /**
     * 服务条款URL
     */
    private static final String TERMS_OF_SERVICE_URL = ";;
    /**
     * 许可证名称
     */
    private static final String LICENSE_NAME = "Apache 2.0";
    /**
     * 许可证URL
     */
    private static final String LICENSE_URL = ";;

    /**
     * 根据@Tag 上的排序，写入x-order
     *
     * @return the global open api customizer
     */
    @Bean
    public GlobalOpenApiCustomizer orderGlobalOpenApiCustomizer() {
        return openApi -> {
            if (openApi.getTags() != null) {
                openApi.getTags().forEach(tag -> {
                    // 使用Map.of简化Map的创建
                    tag.setExtensions(Map.of("x-order", 1));
                });
            }
            if (openApi.getPaths() != null) {
                openApi.addExtension("x-test123", "333");
                openApi.getPaths().addExtension("x-abb", 1);
            }
        };
    }

    @Bean
    public OpenAPI createCustomOpenApi() { // 修改方法名为createCustomOpenApi
        return new OpenAPI()
        .info(new Info()
              .title(API_TITLE)
              .version(API_VERSION)
              .description(API_DESCRIPTION)
              .termsOfService(TERMS_OF_SERVICE_URL)
              .license(new License().name(LICENSE_NAME)
                       .url(LICENSE_URL)));
    }
}

2.3 添加测试的Controller

package com.jie.springbootinit.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 测试接口
 * 
 * @author jie
 */
@RestController
@RequestMapping("/test")
@Tag(name = "测试接口")
public class TestContrller {


    @GetMapping("/hello")
    @Operation(summary = "测试接口")
    public String hello() {
        return "Hello, World!";
    }
}

3、启动项目，查看效果

访问地址：http://localhost:项目端口/doc.html#/home

发送请求

4、Swagger V3（OpenAPI 3）常用注解

本文标签： Spring Boot 30 集成 knife4j 接口文档