NextDoc4j

主题

NextDoc4j 基础配置 ​

基础配置控制 NextDoc4j 的核心功能开关、浏览器访问路径、前后端跨域调试支持以及生产环境一键安全隐身模式。

核心参数速查表 ​

所有配置均以 nextdoc4j 为统一命名空间，支持 Spring Boot 配置文件智能补全：

配置项名称类型默认值说明与约束
nextdoc4j.enabledbooleanfalseNextDoc4j 文档功能总开关。未开启时不注册相关路由与 Bean。
nextdoc4j.doc-pathstring/doc.html自定义文档访问入口（1.4.0+，单段自定义路径如 /docs；非法格式启动 fail-fast）。
nextdoc4j.corsbooleanfalse是否启用跨域支持（CORS），便于前后端分离项目本地联调。
nextdoc4j.productionbooleanfalse生产环境安全隐身模式，启用后彻底禁用文档及 SpringDoc 原始元数据暴露。

完整配置示例 ​

在项目的配置文件中按需开启相关参数，支持 YAML 与 Properties 格式：

config
nextdoc4j:
  # 1. 核心总开关（默认 false）
  enabled: true

  # 2. 自定义文档入口路径（1.4.0+，默认 /doc.html，需为以 / 开头的单段路径）
  doc-path: /docs

  # 3. 启用跨域支持（开发环境前后端联调推荐）
  cors: true

  # 4. 生产环境安全隐身模式（开启后全面禁用并下线文档端点与元数据）
  production: false

关键配置项深度解析 ​

nextdoc4j.enabled核心总控

控制 NextDoc4j 增强文档的全局装配。设为 false 时，Spring 容器不会初始化任何 NextDoc4j 相关的 Controller、Filter 与静态资源映射器，实现零开销。

开发环境: true测试环境: true
nextdoc4j.doc-path1.4.0 新增

支持将默认访问入口 /doc.html 自定义为团队专属别名（如 /docs 或 /api-docs）。系统在启动期会对路径进行严格校验，若路径不合法会触发 Fail-Fast 阻断，避免上线后访问异常。

单段路径推荐需同步鉴权白名单
nextdoc4j.cors联调增强

一键开启内置的 CORS 跨域过滤器。当前后端分离独立部署或开发人员在本地跨域调用 API 接口时，无需额外手写全局 CORS WebMvcConfigurer。

本地联调利器生产建议设 false
nextdoc4j.production安全隐身

生产环境物理级安全隐身开关。设为 true 时，不仅 NextDoc4j UI 入口彻底关闭，还会深度拦截下线 SpringDoc 的 /v3/api-docs 原始元数据暴露，杜绝接口资产外泄。

生产环境: true阻断外网探针

多环境配置矩阵（Dev / Test / Prod） ​

推荐使用 Spring Boot 多环境配置文件（application-dev.yml / application-prod.yml）进行差异化管控：

DEV 环境

本地与开发环境

开启跨域与文档总开关，关闭生产模式，享受全部在线调试与交互能力。

nextdoc4j:
  enabled: true
  cors: true
  production: false
TEST 环境

测试与预发环境

开启文档供 QA 与前端联调验证，关闭跨域支持，保持规范网络链路。

nextdoc4j:
  enabled: true
  cors: false
  production: false
PROD 环境

正式生产环境

开启 production 安全隐身模式，阻断外网探针对接口元数据的刺探。

nextdoc4j:
  enabled: true
  cors: false
  production: true

常见配置误区与 FAQ ​

若 Spring Boot 配置了 server.servlet.context-path: /api 且 nextdoc4j.doc-path: /docs，则实际文档访问地址为 http://localhost:8080/api/docs。