NextDoc4j

主题

快速开始集成 ​

只需简单三步，即可在 Spring Boot 3.4.x / 4.x 项目中完成 NextDoc4j 的最简依赖引入、配置启用与在线调试。

重要架构统一说明

1.4.0 起单套 Starter 统一坐标

NextDoc4j 正式合并为单套 Starter 坐标 nextdoc4j-spring-boot-starter，同时适配 Spring Boot 3.4.x 与 Spring Boot 4.x（单体 WebMvc / WebFlux 与微服务网关共用）。无需再区分 springboot3 或 springboot4 后缀，大幅降低依赖维护复杂度。

三步快速集成（单体服务） ​

单体应用支持 Spring MVC (Servlet) 与 Spring WebFlux (Reactive) 两种底层 Web 栈，按照您的项目架构选择对应的依赖与配置即可。

第一步：添加 Maven 依赖 ​

按宿主项目 Web 栈二选一引入 springdoc UI，宿主自行管控 springdoc 版本，starter 保持完全解耦：

Web 栈类型Spring Boot 版本SpringDoc UI 坐标 (groupId: org.springdoc)推荐 SpringDoc 版本
Servlet / WebMvc3.4.xspringdoc-openapi-starter-webmvc-ui2.8.17
Reactive / WebFlux3.4.xspringdoc-openapi-starter-webflux-ui2.8.17
Servlet / WebMvc4.xspringdoc-openapi-starter-webmvc-ui3.0.3
Reactive / WebFlux4.xspringdoc-openapi-starter-webflux-ui3.0.3
pom.xml
<!-- 1. NextDoc4j 单套统一 Starter (Spring Boot 3.4.x / 4.x 通用) -->
<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-spring-boot-starter</artifactId>
    <version>1.4.1</version>
</dependency>

<!-- 2. SpringDoc WebMvc UI 依赖 (匹配 Spring Boot 3.4.x) -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.17</version>
</dependency>

第二步：配置文件启用 ​

在 application.yml 或 application.properties 中添加启用声明：

config
nextdoc4j:
  enabled: true
  # 可选：自定义文档入口路径（默认 /doc.html，需配置为以 / 开头的单段路径）
  # doc-path: /docs

第三步：启动并访问 ​

启动 Spring Boot 应用，在浏览器中访问以下地址即可进入 NextDoc4j 现代化工作台：

默认端口为 8080，点击上方链接可直接复制。若配置了 nextdoc4j.doc-path 请使用对应的自定义路径。

微服务网关场景快速引入 ​

如果当前服务是 Spring Cloud Gateway 网关聚合服务，1.4.0 起统一引入网关 Starter nextdoc4j-gateway-spring-boot-starter，并自行引入对应网关运行时：

网关架构类型Gateway 运行时坐标 (groupId: org.springframework.cloud)SpringDoc UI 坐标 (groupId: org.springdoc)
Reactive WebFluxspring-cloud-starter-gateway-server-webfluxspringdoc-openapi-starter-webflux-ui
Servlet WebMvcspring-cloud-starter-gateway-server-webmvcspringdoc-openapi-starter-webmvc-ui
gateway
<!-- 1. NextDoc4j 统一网关 Starter -->
<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-gateway-spring-boot-starter</artifactId>
    <version>1.4.1</version>
</dependency>

<!-- 2. Spring Cloud Gateway 运行时 (WebFlux) -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
</dependency>

<!-- 3. SpringDoc Reactive UI -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.8.17</version>
</dependency>

最小可运行 Controller 示例 ​

使用标准的 OpenAPI 3 注解（@Tag、@Operation、@Parameter）即可在 NextDoc4j 中生成具备丰富调试功能的接口卡片：

UserController.java
java
package com.example.demo.controller;

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

@Tag(name = "用户管理模块", description = "提供用户的查询、创建与详情接口")
@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    @Operation(summary = "根据用户 ID 查询详情", description = "根据用户主键返回用户详细档案信息")
    @GetMapping("/{id}")
    public UserVO getUserById(
            @Parameter(description = "用户唯一标识 ID", example = "1001")
            @PathVariable Long id) {
        return new UserVO(id, "NextDoc4j User", "dev@nextdoc4j.top");
    }
}

常见问题与安全拦截排查 ​

集成过程中遇到拦截或资源加载异常时，请对照以下规则快速排查：

请在您的安全框架白名单中放行以下路径（允许匿名访问）：

/doc.html、/webjars/**、/v3/api-docs/**、/swagger-resources/**、/favicon.ico。