java

关注公众号 jb51net

关闭
首页 > 软件编程 > java > SpringBoot集成SpringDoc OpenAPI

SpringBoot集成SpringDoc OpenAPI(替代SpringFox/Swagger2)的完整步骤

作者：快雪时晴-初晴融雪

还在用老旧的SpringFox,本文将手把手教你如何在SpringBoot 2.x和3.x中集成SpringDoc OpenAPI,生成可交互的Swagger UI接口文档,从依赖配置到Controller注解,再到安全放行和常见踩坑排查,全程复制粘贴即可运行,助你轻松实现接口文档自动化,需要的朋友可以参考下

说明：

1、SpringFox（旧 Swagger2）大量存在兼容 bug（SpringBoot2.6+、3.x 报错），

本文使用 SpringDoc OpenAPI 3，页面就是 Swagger UI

2、SpringBoot2.x/ SpringBoot3.x 区分依赖版本，下文标注清楚

3、全程一步一步操作，复制即可运行

前置说明

访问地址最终：http://localhost:你的端口/swagger-ui/index.html

第 1 步：引入 Maven 依赖 pom.xml

情况 A：SpringBoot 3.x（JDK17+）

<!-- SpringDoc OpenAPI3 Swagger -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

情况 B：SpringBoot 2.x（JDK8 / JDK11）

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

引入依赖后，刷新 Maven，等待依赖下载完成。

第 2 步：创建 Swagger 配置类（可选，用于修改文档标题、描述）

新建配置类 SwaggerOpenApiConfig.java，放在你的 config 包下

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerOpenApiConfig {
@Bean
public OpenAPI openAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("项目后端接口文档")     //文档标题
                    .version("V1.0")               //版本
                    .description("所有业务接口在线调试文档")); //描述
}
}

不写这个配置类也能正常打开 swagger，只是文档顶部没有自定义标题。

第 3 步【核心】给你的 Controller 接口添加注解（让接口显示在文档）

OpenAPI3 常用注解对照表

注解

作用

@Tag(name = "模块名称")

加在 Controller 类上，划分接口模块

@Operation(summary = "接口名称",description = "详细描述")

标记单个接口

@Parameter(description = "参数说明")

url 传参说明

@Schema(description = "字段注释")

实体类、DTO 字段注释

其实 不加注解也能用了。SpringDoc 会自动扫描你所有的@RestController，直接生成文档。

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;
@RestController
@RequestMapping("/user")
@Tag(name = "用户管理模块")
public class UserController {
    @GetMapping("/get")
    @Operation(summary = "根据ID获取用户信息", description = "传入用户id，查询基础用户数据")
    public String getUser(Long userId){
        return "用户信息";
    }
}

DTO / 实体类示例（返回对象展示注释）

DTO（Data Transfer Object，数据传输对象）和实体类（Entity）是后端开发中常用的两种数据模型类，它们都可以通过 Swagger/OpenAPI 注解来展示字段说明。

在 Swagger 文档中，当接口返回或接收这些对象时，字段上的 @Schema 注解能让文档清晰地展示每个字段的含义和示例值。

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
@Data
@Schema(description = "用户返回实体")
public class UserDTO {
@Schema(description = "用户唯一ID", example = "1001")
private Long userId;

@Schema(description = "用户姓名", example = "张三")
private String userName;

@Schema(description = "用户邮箱", example = "zhangsan@example.com")
private String email;

@Schema(description = "创建时间", example = "2023-10-01 12:00:00")
private String createTime;
}

关键点：

@Schema(description = "...")：用于描述整个类或单个字段的作用。

@Schema(example = "...")：提供字段的示例值，方便在 Swagger UI 中直接测试。

实体类（如 JPA Entity）的注解用法完全相同，但通常用于数据库映射。

确保导入正确的包：import io.swagger.v3.oas.annotations.media.Schema;，不要用旧版 Swagger2 的 @ApiModel。

这样配置后，Swagger 文档中该对象的字段就会显示清晰的注释和示例，提升接口文档的可读性。

第 4 步：启动项目，访问文档地址

http://localhost:8080/swagger-ui/index.html

把 8080 替换成你项目的 server.port 端口。

如果打不开页面：往下看【常见问题排查】

成功了

第 5 步（可选）：SpringSecurity / 拦截器放行 swagger 资源

如果项目使用 SpringSecurity、自定义拦截器，会拦截 swagger 地址，页面无法加载，需要放行地址： 放行路径清单：

/v3/api-docs/**
/swagger-ui/**
/swagger-ui/index.html

SpringSecurity 放行示例

@Override
public void configure(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests()
            .requestMatchers("/v3/api-docs/**","/swagger-ui/**").permitAll()
            .anyRequest().authenticated();
}

自定义 WebMvc 拦截器放行

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(loginInterceptor)
            .addPathPatterns("/**")
            .excludePathPatterns("/v3/api-docs/**","/swagger-ui/**");
}

第 6 步（可选）区分环境：只开发环境开启 Swagger

一般生产环境关闭接口文档，使用 @ConditionalOnProperty 修改配置类：

@Configuration
// yml配置 springdoc.enable=true 才开启
@ConditionalOnProperty(name = "springdoc.enable", havingValue = "true")
public class SwaggerOpenApiConfig {
    // ...代码不变
}

application.yml

springdoc:
  enable: true # dev开启；prod改为false

高频踩坑排查清单（重点！）

问题 1：打开页面，但是一片空白，看不到自己写的接口

  1. Controller 必须加 @RestController
  2. 接口方法必须是 public
  3. 启动项目后不要直接访问静态 html，先让 Spring 加载所有 Controller
  4. 检查请求路径是否有统一前缀 server.servlet.context-path，访问地址要带上前缀

问题 2：404 找不到页面

核对地址！

✅ 正确：/swagger-ui/index.html

❌ 旧 swagger2 地址 /swagger-ui.html 在 SpringDoc 中失效

问题 3：实体类返回值不显示注释

确认导入注解包：

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

不要导错旧 swagger2 的@ApiModel

问题 4：SpringBoot3 启动报错

必须使用 springdoc-openapi-starter-webmvc-ui，不能使用 2.x 旧依赖

补充：如果你执意使用老版本 Swagger2（SpringFox，不推荐）

pom 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

配置类

import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                // 重点！修改为你的controller包路径
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                .build();
    }
}

访问地址：http://localhost:8080/swagger-ui.html

SpringBoot 2.6 以上必须额外配置 yml 解决路径匹配报错

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

问题5、本地有Swagger UI文件吗

你在项目目录里找不到任何 swagger-ui 的 HTML/CSS/JS 文件

Swagger UI 的静态文件打包在 JAR 依赖包内部

以上就是SpringBoot集成SpringDoc OpenAPI(替代SpringFox/Swagger2)的完整步骤的详细内容，更多关于SpringBoot集成SpringDoc OpenAPI的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:
阅读全文