SpringBoot 3 整合 Swagger 3

1. 整合概述

1.1 技术栈版本

  • Spring Boot: 3.3.0
  • Java: 17+
  • Swagger: OpenAPI 3.0
  • 实现方式: SpringDoc OpenAPI + Knife4j

1.2 整合目标

  • 实现 API 文档自动生成
  • 提供交互式 API 测试界面
  • 支持 API 文档访问控制
  • 兼容 Spring Boot 3.x 特性

2. 详细整合步骤

步骤 1: 添加依赖配置

打开 pom.xml 文件，添加以下依赖：

<!-- SpringDoc OpenAPI 3.0 核心依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.6.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>
<!-- Swagger 3 注解依赖 -->
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.25</version>
</dependency>
<!-- Knife4j 增强依赖 (可选，提供更友好的界面) -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

注意事项：

  • Spring Boot 3.x 必须使用 jakarta 版本的 Knife4j
  • 确保所有依赖版本兼容

步骤 2: 配置 application.yml 文件

打开 application.yml 文件，添加以下配置：

# 接口文档配置
knife4j:
  # 基础认证配置
  basic:
    enable: true  # 是否启用基础认证
    username: root  # 认证用户名
    password: password  # 认证密码
  # OpenAPI 配置
  openapi:
    title: "智能图片社区后端API"  # API 文档标题
    version: 1.0  # API 文档版本
    # 分组配置
    group:
      default:  # 默认分组
        api-rule: package  # API 扫描规则
        api-rule-resources:  # 扫描的包路径
          - com.spc.smartpiccommunitybackend.controller  # 控制器包路径

配置说明：

  • basic.enable: 生产环境建议开启认证保护
  • api-rule-resources: 配置为实际的控制器包路径
  • 可根据环境需求调整配置

步骤 3: 创建配置类

创建 Knife4jConfig.java 文件：

package com.spc.smartpiccommunitybackend.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;

/**
 * SpringDoc OpenAPI配置
 * 兼容Spring Boot 3.x
 */
@Configuration
public class Knife4jConfig {

    /**
     * 配置OpenAPI 3.0
     */
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(apiInfo());
    }

    /**
     * 配置API信息
     */
    private Info apiInfo() {
        return new Info()
                .title("智能图片社区后端API")
                .description("智能图片社区后端API接口文档，包含用户、图片、评论等核心功能")
                .version("1.0")
                .contact(new Contact()
                        .name("spc")
                        .email("xxxxxxxxxx@qq.com")
                        .url("http://localhost:8645/api/doc.html"));
    }
}

配置说明：

  • 通过 @Bean 注解创建 OpenAPI 对象
  • 配置 API 文档的基本信息
  • 可根据项目需求添加更多配置

步骤 4: 为控制器添加注解

为控制器类添加注解：

package com.spc.smartpiccommunitybackend.controller;

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

@RestController
@RequestMapping("/comment")
@Tag(name = "评论接口", description = "提供评论的增删改查功能")
public class CommentController {

    @PostMapping("/add")
    @Operation(summary = "添加评论", description = "用户添加评论，需要登录认证")
    public BaseResponse<Long> addComment(@RequestBody @Valid CommentAddRequest commentAddRequest,
                                         HttpServletRequest request) {
        // 方法实现...
    }

    @PostMapping("/delete")
    @Operation(summary = "删除评论", description = "用户删除自己的评论，需要登录认证")
    public BaseResponse<Boolean> deleteComment(@RequestParam Long commentId,
                                              HttpServletRequest request) {
        // 方法实现...
    }
}

注解说明：

  • @Tag: 标记控制器类，设置控制器名称和描述
  • @Operation: 标记接口方法，设置接口摘要和描述

步骤 5: 为模型类添加注解

为模型类添加注解：

package com.spc.smartpiccommunitybackend.common;

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

@Data
public class PageRequest {

    @Schema(description = "当前页号", example = "1", defaultValue = "1")
    private int current = 1;

    @Schema(description = "页面大小", example = "10", defaultValue = "10")
    private int pageSize = 10;

    @Schema(description = "排序字段", example = "createTime")
    private String sortField;

    @Schema(description = "排序顺序（默认降序）", example = "descend", defaultValue = "descend")
    private String sortOrder = "descend";
}

注解说明：

  • @Schema: 标记模型字段，设置字段描述、示例值和默认值
  • description: 字段描述
  • example: 示例值
  • defaultValue: 默认值

步骤 6: 为请求参数添加注解

为方法参数添加注解：

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

@GetMapping("/get")
@Operation(summary = "获取评论详情")
public BaseResponse<CommentVO> getCommentById(
        @Parameter(description = "评论ID", required = true, example = "1") 
        @RequestParam Long commentId) {
    // 方法实现...
}

注解说明：

  • @Parameter: 标记方法参数，设置参数描述、是否必填和示例值
  • required: 是否必填
  • example: 示例值

3. 访问 API 文档

3.1 启动应用

# 构建项目
mvn clean install -DskipTests

# 启动应用
java -jar target/smart-pic-community-backend-0.0.1-SNAPSHOT.jar

3.2 访问路径

访问方式 路径 说明
Knife4j 界面 http://localhost:8645/api/doc.html 增强版 API 文档界面，需要认证
Swagger UI 界面 http://localhost:8645/api/swagger-ui/index.html 标准 Swagger 界面
OpenAPI 规范 http://localhost:8645/api/v3/api-docs JSON 格式的 API 规范

3.3 认证访问

  1. 访问 Knife4j 界面：http://localhost:8645/api/doc.html
  2. 输入认证信息：
    • 用户名：root
    • 密码：password
  3. 验证访问：确认能够正常访问 API 文档

4. 多环境配置

4.1 开发环境配置

application-dev.yml：

knife4j:
  basic:
    enable: false  # 开发环境不需要认证
  openapi:
    title: "智能图片社区API (开发环境)"
    version: 1.0-SNAPSHOT

4.2 生产环境配置

application-prod.yml：

knife4j:
  basic:
    enable: true  # 生产环境需要认证
    username: admin
    password: secure_password_2024
  openapi:
    title: "智能图片社区API (生产环境)"
    version: 1.0

4.3 环境切换

application.yml：

spring:
  profiles:
    active: dev  # 切换环境：dev、test、prod

5. 功能验证

5.1 文档生成验证

  1. 接口完整性：检查所有控制器接口是否都已生成文档
  2. 参数正确性：验证请求参数和响应模型是否正确显示
  3. 描述完整性：检查接口和字段描述是否完整

5.2 交互测试验证

  1. 接口调用：测试通过文档界面调用接口
  2. 参数传递：验证参数是否正确传递
  3. 响应处理：检查响应结果是否正确显示

5.3 认证功能验证

  1. 认证生效：验证未登录时无法访问文档
  2. 认证通过：验证输入正确用户名密码后可以访问
  3. 权限控制：检查认证是否按配置生效

6. 常见问题与解决方案

6.1 依赖冲突问题

问题：添加依赖后出现 NoClassDefFoundError 或 ClassNotFoundException

解决方案：

  1. 清理 Maven 缓存：
mvn dependency:purge-local-repository
  1. 统一依赖版本：确保所有 Spring 相关依赖版本一致
  2. 排除冲突依赖：
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

6.2 注解使用问题

问题：注解导入错误或使用方式错误

解决方案：

  1. 正确导入注解：
    • 控制器注解：io.swagger.v3.oas.annotations.tags.Tag、io.swagger.v3.oas.annotations.Operation
    • 模型注解：io.swagger.v3.oas.annotations.media.Schema
    • 参数注解：io.swagger.v3.oas.annotations.Parameter
  2. 正确使用注解：
    • @Tag(name = "接口名称", description = "接口描述")
    • @Operation(summary = "方法摘要", description = "方法描述")
    • @Schema(description = "字段描述", example = "示例值")

6.3 文档访问问题

问题：API 文档访问 404 或 500 错误

解决方案：

  1. 检查路径：确保访问路径正确，Spring Boot 3 路径为 /swagger-ui/index.html
  2. 检查配置：确认 context-path 配置，项目路径为 /api/swagger-ui/index.html
  3. 检查版本兼容：Spring Boot 3.2+ 需使用 SpringDoc 3.0.0+
  4. 检查控制器注解：确保控制器类使用了 @RestController 注解

6.4 认证配置问题

问题：配置了认证但不生效

解决方案：

  1. 检查配置：确保 knife4j.basic.enable 设置为 true
  2. 检查依赖：确保添加了 Knife4j 依赖
  3. 检查路径：认证只对 Knife4j 界面生效，Swagger UI 界面不受影响
  4. 重启应用：配置修改后需要重启应用

7. 性能优化

7.1 扫描范围优化

knife4j:
  openapi:
    group:
      default:
        api-rule: package
        api-rule-resources:
          - com.spc.smartpiccommunitybackend.controller
        include-path-patterns:
          - /api/**
        exclude-path-patterns:
          - /api/health/**
          - /api/metrics/**

7.2 缓存配置

springdoc:
  cache:
    disabled: false
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html

7.3 生产环境优化

# 生产环境禁用 API 文档
knife4j:
  enable: false

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

8. 高级功能

8.1 API 分组

knife4j:
  openapi:
    group:
      default:
        api-rule: package
        api-rule-resources:
          - com.spc.smartpiccommunitybackend.controller
      user:
        api-rule: package
        api-rule-resources:
          - com.spc.smartpiccommunitybackend.controller.user
      picture:
        api-rule: package
        api-rule-resources:
          - com.spc.smartpiccommunitybackend.controller.picture

8.2 全局参数配置

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(apiInfo())
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
            .components(new Components()
                    .addSecuritySchemes("bearerAuth", new SecurityScheme()
                            .type(SecurityScheme.Type.HTTP)
                            .scheme("bearer")
                            .bearerFormat("JWT")));
}

8.3 响应结果配置

@Bean
public OperationCustomizer operationCustomizer() {
    return (operation, handlerMethod) -> {
        operation.addResponses("401", new ApiResponse()
                .description("未授权，需要登录")
                .content(new Content().addMediaType(MediaType.APPLICATION_JSON_VALUE, 
                        new MediaType().schema(new Schema<ErrorResponse>().$ref("#/components/schemas/ErrorResponse"))));
        return operation;
    };
}

9. 项目实际应用示例

9.1 完整配置示例

pom.xml 依赖：

<!-- SpringDoc OpenAPI 3.0 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.6.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.6.0</version>
</dependency>
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.2.25</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

application.yml 配置：

knife4j:
  basic:
    enable: true
    username: root
    password: password
  openapi:
    title: "智能图片社区后端API"
    version: 1.0
    group:
      default:
        api-rule: package
        api-rule-resources:
          - com.spc.smartpiccommunitybackend.controller

9.2 实际访问效果

  1. Knife4j 界面：
    • 地址：http://localhost:8645/api/doc.html
    • 特点：界面美观，功能丰富，支持认证
  2. Swagger UI 界面：
    • 地址：http://localhost:8645/api/swagger-ui/index.html
    • 特点：标准 Swagger 界面，功能完整
  3. API 规范：
    • 地址：http://localhost:8645/api/v3/api-docs
    • 特点：JSON 格式，可用于导入其他工具
# spring boot # 后端 # java
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

沐曦股份曦云C系列GPU Day 0 适配智谱GLM-5.1 全栈技术领跑国产AI生态

avatar AtomGit开源社区
cover

AI Coding实战！我用 AI 全程编码了一个企业级后台管理框架 Forge Admin

avatar AtomGit开源社区
cover

SAS与SATA硬盘深度解析：性能、可靠性与应用场景的终极较量

avatar AtomGit开源社区