30分钟内搭建一个全能轻量级springboot 3.4 + 脚手架 ＜2＞ 5分钟集成好最新版本的开源swagger ui --- knife4j，并使用ui操作调用接口

快速导航

<1> 5分钟快速创建一个springboot web项目
<2> 5分钟集成好最新版本的开源swagger ui，并使用ui操作调用接口
<3> 5分钟集成好druid并使用druid自带监控工具监控sql请求
<4> 5分钟集成好mybatisplus并使用mybatisplus generator自动生成代码
<5> 5分钟集成好caffeine并使用注解操作缓存
<6> 5分钟集成好前端页面

demo项目代码下载

这篇文章会讲解如何集成最新版本的开源swagger ui ----- knife4j。

knife4j官网地址

一、 集成knife4j

集成 knife4j 非常便捷，只需要加入官方依赖，然后简单配置即可。这里只展示简单的配置，更多的配置可参考 knife4j 官网文档进行修改。

1. 加入dependency manager

<dependencyManagement>
	<dependencies>
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>knife4j-dependencies</artifactId>
			<version>4.5.0</version>
			<type>pom</type>
			<scope>import</scope>
		</dependency>
	</dependencies>
</dependencyManagement>

2. 集成依赖

<dependency>
	<groupId>cn.hutool</groupId>
	<artifactId>hutool-all</artifactId>
	<version>5.8.10</version>
</dependency>
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
</dependency>

3. java config 配置knife4j

项目目录结构如下：

配置文件详细内容如下：

package com.example.demo.config; // 改成自己的package地址

/*
 * Copyright (C) 2018 Zhejiang xiaominfo Technology CO.,LTD.
 * All rights reserved.
 * Official Web Site: http://www.xiaominfo.com.
 * Developer Web Site: http://open.xiaominfo.com.
 */
import cn.hutool.core.util.RandomUtil;
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.HashMap;
import java.util.Map;

/***
 * 创建Swagger配置
 * @since:knife4j-springdoc-openapi-demo 1.0
 * @author <a href="mailto:xiaoymin@foxmail.com">xiaoymin@foxmail.com</a>
 * 2020/03/15 20:40
 */
@Configuration
public class SwaggerConfig {
    /**
     * 根据@Tag 上的排序，写入x-order
     *
     * @return the global open api customizer
     */
    @Bean
    public GlobalOpenApiCustomizer orderGlobalOpenApiCustomizer() {
        return openApi -> {
            if (openApi.getTags()!=null){
                openApi.getTags().forEach(tag -> {
                    Map<String,Object> map=new HashMap<>();
                    map.put("x-order", RandomUtil.randomInt(0,100));
                    tag.setExtensions(map);
                });
            }
            if(openApi.getPaths()!=null){
                openApi.addExtension("x-test123","333");
                openApi.getPaths().addExtension("x-abb",RandomUtil.randomInt(1,100));
            }

        };
    }

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("XXX用户系统API")
                        .version("1.0")
                        .description( "Knife4j集成springdoc-openapi示例")
                        .termsOfService("http://doc.xiaominfo.com")
                        .license(new License().name("Apache 2.0")
                                .url("http://doc.xiaominfo.com")));
    }


}

修改TestController 代码

@RestController
@RequestMapping("/test")
@Tag(name = "User API", description = "用户管理相关接口")
public class TestController {

    @GetMapping("")
    @Operation(method = "test", summary = "测试接口")
    public String test(){
        return "test";
    }

}

4. 启动服务并访问

启动服务之后访问 http://localhost:8080/doc.html

5. 点击发送可以直接发送请求，响应内容为test

二、新版本swagger注解使用教程

在新版本的 Swagger（现在是 Springdoc OpenAPI）中，注解的使用方式有所变化，主要基于 io.swagger.v3.oas.annotations 下的注解。以下是如何在新版本中正确使用 Swagger 注解的指南：

---

1. 添加依赖

确保在项目中包含正确的依赖。如果你使用的是 Spring Boot，建议使用 springdoc-openapi。

1.1 Maven

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

1.2 Gradle

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

---

2. 基本配置

springdoc-openapi 默认无需额外配置即可自动生成 API 文档。如果需要自定义设置，可以在 application.properties 中进行配置：

springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

访问文档地址：

• OpenAPI JSON: http://localhost:8080/api-docs
• Swagger UI: http://localhost:8080/swagger-ui.html

---

3. 控制器注解使用

新版本注解基于 io.swagger.v3.oas.annotations，以下是常见的注解用法。

3.1 类级别注解

import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/users")
@Tag(name = "User API", description = "用户管理相关接口")
public class UserController {
    // ...
}

3.2 方法级别注解

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    @Operation(
        summary = "根据ID获取用户",
        description = "通过用户ID查询用户详细信息"
    )
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "成功获取用户信息"),
        @ApiResponse(responseCode = "404", description = "用户未找到")
    })
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        // 示例实现
        return ResponseEntity.ok(new User(id, "John Doe"));
    }
}

---

4. 参数说明

通过 @Parameter 或 @Parameters 注解为接口参数添加文档说明。

import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;

@GetMapping
@Operation(summary = "获取用户列表")
public List<User> getUsers(
    @Parameter(description = "页码", example = "1")
    @RequestParam int page,

    @Parameter(description = "每页数量", example = "10")
    @RequestParam int size
) {
    // 示例实现
    return List.of(new User(1L, "John Doe"));
}

---

5. 请求体和响应体描述

使用 @RequestBody 和 @Schema 为复杂对象定义文档信息。

5.1 定义请求体

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户请求体")
public class CreateUserRequest {
    @Schema(description = "用户名", example = "John")
    private String username;

    @Schema(description = "邮箱地址", example = "john.doe@example.com")
    private String email;

    // Getters and Setters
}

5.2 控制器使用请求体

import io.swagger.v3.oas.annotations.parameters.RequestBody;

@PostMapping
@Operation(summary = "创建新用户")
public ResponseEntity<User> createUser(
    @RequestBody(description = "用户信息", required = true)
    @Valid @org.springframework.web.bind.annotation.RequestBody CreateUserRequest request
) {
    // 示例实现
    return ResponseEntity.ok(new User(1L, request.getUsername()));
}

---

6. 自定义全局 API 信息

通过 @OpenAPIDefinition 配置全局元信息。

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.Contact;

@OpenAPIDefinition(
    info = @Info(
        title = "示例 API 文档",
        version = "1.0",
        description = "示例项目的 API 文档",
        contact = @Contact(name = "开发者支持", email = "support@example.com")
    )
)
@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

---

7. 支持枚举类型

为枚举添加 @Schema 注解，生成文档时会展示可选值。

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户角色", example = "ADMIN")
public enum UserRole {
    ADMIN, USER, GUEST
}

---

通过以上方式，你可以使用新版本的 Swagger 注解全面定义 API 文档，帮助前后端高效协作！如需更深入的使用说明，可以进一步探索 Springdoc 的官方文档。

总结

1. 新版本的swagger不在使用@Api/@ApiOperation等方式进行接口定义了，要用新版本的注解去定义接口。
2. knife4j 支持微服务方式，不需要每个服务都集成ui，如有需要查看官方文档进行定义即可。
3. knife4j 支持多租户，多模块形式定义文档。