NextDoc4j 快速开始

⚠️ 版本要求

JDK： 17+
Spring Boot： 3.5.x 或 4.x（1.4.0 起单体 / 网关均为单套坐标，Boot 3 / 4 共用 artifact）
当前版本： 1.4.0

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

第一步：添加 Maven 依赖（最简方式）

1.4.0 起：nextdoc4j-bom 只管理 top.nextdoc4j 自身模块版本；Spring Boot / springdoc 由宿主自行引入（starter 内对 springdoc 为 optional，不会传递）。

按 Web 栈二选一引入 springdoc UI（坐标 groupId 均为 org.springdoc）：

Web 栈	Maven 坐标	说明
Servlet / WebMvc	`springdoc-openapi-starter-webmvc-ui`	配合 `spring-boot-starter-web`
Reactive / WebFlux	`springdoc-openapi-starter-webflux-ui`	配合 `spring-boot-starter-webflux`

版本对照（与官方 demo 一致）：

Spring Boot	springdoc 主版本	推荐版本（`springdoc-openapi-bom`）
3.5.x	2.x	`2.8.17`
4.x	3.x	`3.0.3`

WebMvc（Boot 3 示例）WebFlux（Boot 3 示例）WebMvc（Boot 4 示例）

xml

<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-spring-boot-starter</artifactId>
    <version>1.4.0</version>
</dependency>
<!-- 宿主自行引入 springdoc UI（版本请按 Boot 主版本选择，见上表） -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.17</version>
</dependency>

xml

<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-spring-boot-starter</artifactId>
    <version>1.4.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.8.17</version>
</dependency>

xml

<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-spring-boot-starter</artifactId>
    <version>1.4.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>3.0.3</version>
</dependency>

推荐方式（可选）：使用 BOM 统一版本

nextdoc4j-bom 与 springdoc-openapi-bom 职责分离：前者只钉 NextDoc4j 模块，后者只钉 springdoc。

xml

<!-- 放到 dependencyManagement > dependencies 中 -->
<!-- springdoc 不在 Spring Boot BOM 内：Boot 3 用 2.x，Boot 4 用 3.x -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-bom</artifactId>
    <version>2.8.17</version><!-- Boot 4 请改为 3.0.3 -->
    <type>pom</type>
    <scope>import</scope>
</dependency>
<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-bom</artifactId>
    <version>1.4.0</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

<!-- 放到 dependencies 中（版本由上方 BOM 管理） -->
<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-spring-boot-starter</artifactId>
</dependency>
<!-- WebMvc；WebFlux 请改用 springdoc-openapi-starter-webflux-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

从 1.3.x 升级

旧坐标 nextdoc4j-springboot3-starter / nextdoc4j-springboot4-starter、nextdoc4j-bom-springboot3/4 已合并为上表单套坐标，请直接替换 artifactId，并自行补上匹配的 springdoc UI 依赖（见上表）。

第二步：配置启用

在 application.yml 或 application.properties 中添加配置：

yamlproperties

yaml

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

properties

nextdoc4j.enabled=true
# nextdoc4j.doc-path=/docs

第三步：启动并访问

在浏览器中打开以下地址（若配置了 doc-path，请使用对应路径）：

text

http://localhost:8080/doc.html

💡 提示：请将 8080 替换为您实际的应用端口号。

网关场景快速引入

如果当前服务是 Spring Cloud Gateway，1.4.0 起统一引入网关 Starter，并自行补齐 Gateway 运行时与 springdoc UI：

xml

<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-gateway-spring-boot-starter</artifactId>
    <version>1.4.0</version>
</dependency>

网关类型	Gateway 运行时坐标	springdoc UI 坐标
WebFlux	`org.springframework.cloud:spring-cloud-starter-gateway-server-webflux`	`org.springdoc:springdoc-openapi-starter-webflux-ui`
WebMvc	`org.springframework.cloud:spring-cloud-starter-gateway-server-webmvc`	`org.springdoc:springdoc-openapi-starter-webmvc-ui`

完整 XML 示例（Boot 3 + Gateway WebFlux）：

xml

<dependency>
    <groupId>top.nextdoc4j</groupId>
    <artifactId>nextdoc4j-gateway-spring-boot-starter</artifactId>
    <version>1.4.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.8.17</version><!-- Boot 4 请用 3.0.3，或由 springdoc-openapi-bom 管理 -->
</dependency>

然后在配置中启用：

yaml

nextdoc4j:
  enabled: true
  gateway:
    auto-discovery: true

路由定义位置：
Gateway WebFlux 使用 spring.cloud.gateway.server.webflux.routes，
Gateway WebMvc 使用 spring.cloud.gateway.server.webmvc.routes。

💡 StripPrefix 等过滤器会参与外部文档路径推导；子服务 swagger-config 分组 URL 会自动改写为服务相对地址。详见网关聚合插件。

从 1.3.x 升级

旧的 nextdoc4j-springboot3/4-gateway-webflux-starter / ...-webmvc-starter 已统一为 nextdoc4j-gateway-spring-boot-starter。

技术支持

如在使用过程中遇到问题或有改进建议，欢迎通过以下方式参与和反馈：

nextdoc4j：核心后端模块
nextdoc4j-ui：可视化前端界面
nextdoc4j-demo：基于 SpringDoc 的使用示例，展示常见集成与扩展方式

⚠️ 提示

如文档或示例描述不清晰，您可以直接在示例仓库中提交 PR，我们会在合并后第一时间同步适配接口。

更新说明

NextDoc4j 项目持续迭代中，多个平台仓库保持同步更新。建议关注最新版本以获得更好的兼容性和稳定性。

NextDoc4j 快速开始 ​

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

第一步：添加 Maven 依赖（最简方式） ​

第二步：配置启用 ​

第三步：启动并访问 ​

网关场景快速引入 ​

技术支持 ​

更新说明 ​