NextDoc4j

主题

更新日志 ​

v1.3.1 (2026-04-27) ​

新增功能 ​

  • 前端
    • 新增接口文档调试面板状态记忆能力，可在页面切换或重新进入后自动恢复调试视图状态。
    • 新增请求体文本草稿缓存与恢复能力，支持 json、raw、xml 等多种文本类型的独立保存与切换恢复。
    • 新增调试面板加载中与空状态提示，提升接口文档页的状态反馈体验。

功能优化 ​

  • 前端
    • 优化标签页关闭逻辑，关闭全部标签页时优先保留首页，提升操作一致性。
    • 优化路由兜底处理，访问无效页面或异常跳转时可自动回退到可用页面。
    • 优化接口文档页调试状态同步时机，减少状态覆盖、显示延迟和异常闪动问题。
    • 优化请求参数、请求体和调试状态的数据渲染机制，通过唯一行键提升表格更新稳定性。
    • 优化 JSON 示例展示结构与样式，长内容场景下支持横向滚动，提升可读性。
    • 优化字段说明与注释区域布局，改善复杂数据结构下的展示效果。

BUG 修复 ​

  • 前端
    • 修复请求体草稿在类型切换、页面隐藏及只读视图场景下可能丢失或异常刷新的问题。
    • 修复 Query 参数编辑过程中因行键不稳定导致的光标失焦问题。
    • 修复关闭标签页后可能进入无效路由、回退异常或目标页面不存在的问题。
    • 修复 JSON 示例在长内容场景下出现越界、挤压或显示不完整的问题。

依赖更新 ​

  • 后端
    • Spring Boot 3 升级：3.5.11 -> 3.5.14
    • Spring Boot 4 升级：4.0.3 -> 4.0.6

v1.3.0 (2026-04-16) ​

新增功能 ​

  • 后端（网关聚合运行时）

    • 新增 Spring Cloud Gateway WebMvc 聚合文档支持，提供独立的 gateway-webmvc-starter、路由定位器、响应重写过滤器与自动配置桥接，使 Servlet / WebMvc 网关也可完成文档自动发现、聚合与安全方案注入
    • 为 WebFlux / WebMvc 网关统一引入中立路由模型与定位器接口，新增 nextdoc4j-plugin-gateway-core、NextDoc4jGatewayRouteDefinitionLocator、GatewayRouteDefinition / GatewayPredicateDefinition，支持跨运行时复用路由发现与元数据解析逻辑

  • 后端（Starter 与模块体系）

    • 新增 nextdoc4j-common 聚合模块，并将基础认证、扩展解析、资源处理等通用能力下沉到 nextdoc4j-common-springboot3/4
    • 按 Spring Boot 3/4 与运行时类型拆分 Starter，补齐常规 Starter、Gateway WebFlux Starter、Gateway WebMvc Starter，便于按需接入

  • 前端（接口详情工作台）

    • 新增完整的接口详情工作台：参数视图、模式视图、请求/响应 JSON 示例、多示例切换，以及 oneOf / allOf / anyOf 组合类型展示与交互
    • 新增请求/响应 TS 代码示例面板，以及请求参数、响应参数的 TS 实体代码生成能力

  • 前端（在线调试与导出）

    • 新增高级在线调试能力，支持 Path / Query / Header / Cookie / Body 联动编辑、请求缓存、Content-Type 切换、form-data / file 上传、复制 BaseURL / Path，以及二进制、图片 / Base64 响应处理
    • 新增文档导出中心，支持全局参数管理、自定义导出范围、聚合服务导出，以及 Markdown / HTML / OpenAPI JSON / Docx / PDF 多格式导出

  • 前端（聚合文档与检索）

    • 新增实体模型 JSON 示例展示，并增强实体详情页的结构展示
    • 增强微服务聚合文档与全局搜索能力，支持聚合服务展示、路径高亮和更完整的搜索索引

功能优化 ​

  • 后端

    • 重构 Spring Boot 3/4 版本层父 POM 与模块层级，统一公共依赖声明并梳理 Starter 边界，降低不同运行时之间的耦合与重复维护成本
    • 优化网关自动发现链路：统一自动配置与手动配置的文档入口模型，增强 metadata、Path Predicate、URI 与服务 context-path 的组合解析能力，服务名、文档路径与 serviceId 提取更稳定
    • 优化自动配置装配边界，WebFlux / WebMvc 按运行时独立生效，网关聚合、基础认证、资源过滤和扩展配置的 Bean 组合更清晰

  • 前端

    • 接口详情页整体重构，参数区域、自适应布局、折叠交互、Schema 切换和调试联动体验明显增强
    • 优化 JSON Viewer 与大响应渲染性能，增加分块渲染与滚动位置保留，长文档和大 JSON 的可用性更好
    • 持续增强文档导出页，补齐权限 / 鉴权信息、响应示例、排序规则和预览性能，导出预览加入虚拟滚动
    • 持续优化在线调试体验，请求参数表、代码格式、响应处理逻辑、缓存恢复和调试区交互更稳定
    • 菜单、侧边栏、全局搜索和路由生成逻辑做了多轮性能与交互优化，搜索匹配和文档定位更自然
    • 工程侧补充系统暗黑模式跟随、首页版本号从后端 x-nextdoc4j.version 读取、统一 OpenAPI 与在线调试超时，并移除了前端定时检查更新 / ws 相关配置

BUG 修复 ​

  • 后端

    • 修复 Spring Cloud Gateway MVC 场景下原先仅覆盖 WebFlux 的能力缺口，补齐 Servlet / WebMvc 网关场景下的路由读取、文档聚合与响应改写链路
    • 修复不同网关实现与 Spring Boot 3/4 Starter 中通用类分散、装配边界混杂的问题，避免错误模块被引入或重复维护
    • 修复路由元数据解析的兼容性边界，增强 routesMap、空路由 / 空谓词、嵌套 nextdoc4j metadata、缺省 URI 与服务名回退等场景下的兜底处理

  • 前端

    • 修复在线调试 URL 解析里 pathAndSearch 可能为空的问题，以及 form-data 文件上传展示、悬浮提示和内容类型处理异常
    • 修复接口详情页切换标签时的展开闪动、状态重置、嵌套参数必填识别错误、空 JSON 结构展示异常
    • 修复 Schema 解析边界问题，包括数组 items 的 $ref 解析、枚举值为 0 被过滤、多内容类型响应渲染异常等
    • 修复聚合模式下错误命中展示、聚合在线测试适配、全局认证折叠样式、图标响应式解析和重复主题配置问题
    • 修复偏好设置中的水印开关不生效，并同步优化相关文案来源和显示逻辑

依赖更新 ​

  • 后端
    • Spring Boot 3 升级：3.5.11 -> 3.5.13
    • Spring Cloud（Spring Boot 3）升级：2025.0.0 -> 2025.0.2
    • Spring Boot 4 升级：4.0.3 -> 4.0.5
    • Springdoc 升级：2.8.16 -> 2.8.17（Spring Boot 3）
    • Springdoc（Spring Boot 4）升级：3.0.2 -> 3.0.3
    • Swagger 升级：2.2.45 -> 2.2.47
    • Sa-Token 升级：1.44.0 -> 1.45.0（Spring Boot 3）

v1.2.0 (2026-03-24) ​

新增功能 ​

  • 后端（模块与运行时）

    • 重构模块结构以适配 Spring Boot 3/4，新增 nextdoc4j-bom-springboot3/4 与 nextdoc4j-starter 聚合结构，并将 Web 运行时能力下沉到 Starter 体系

  • 后端（网关能力）

    • 新增微服务 swagger-config 访问配置
    • 支持接口免鉴权规则并改进文档路由管理

  • 后端（插件能力）

    • 新增 Sa-Token 安全元数据操作定制器支持

  • 前端（全局搜索）

    • 统一构建全局搜索索引，支持路径检索、高亮展示及网关聚合场景搜索
    • 调整搜索面板展示与交互，增强方法标签与结果布局可读性

  • 前端（聚合与导出）

    • 支持基于网关 OpenAPI 配置的聚合服务展示
    • 新增全局参数管理与文档导出能力，支持按分组/接口选择自定义范围
    • 支持微服务聚合文档导出与 docx 格式导出

  • 前端（体验增强）

    • 支持实体菜单描述悬浮提示
    • 支持根据系统暗色模式自动切换主题
    • 新增在线调试请求缓存能力

功能优化 ​

  • 后端

    • 统一并精简配置属性与自动配置模型：使用 NextDoc4jPropertiesMetadata 替换旧配置属性，网关配置改用 @ConfigurationProperties
    • 重构网关与安全模块边界，移除冗余默认 OpenAPI Bean/网关核心依赖，安全包路径由 security.core 迁移至 security.schemes
    • 提取并复用基础工具能力（基础认证、资源处理、路径匹配等），并优化异常处理与默认元数据赋值

  • 前端

    • 优化菜单图标处理、全局认证路由逻辑、聚合路由初始化与服务数据获取流程
    • 优化导出页面布局、参数显示、筛选逻辑与权限描述
    • 重构 Markdown 目录组件并优化样式与交互
    • 优化文件上传状态管理、必填字段处理与请求体变更事件通知机制

BUG 修复 ​

  • 后端

    • 统一 POM 版本并移除 nextdoc4j-dependencies 模块，修复构建结构问题
    • 修复 Spring Boot 4 场景下 Jackson 导入路径问题，兼容 springdoc/swagger 传入 JavaType
    • 修复网关安全方案处理与路径模式转换逻辑（增强 Ant 风格匹配）
    • 通过 @ConditionalOnMissingBean 避免安全配置属性重复注入

  • 前端

    • 修复全局检索方法标签样式和布局显示问题
    • 修正上传文件类型断言顺序
    • 修复聚合模式下错误命中展示问题

依赖更新 ​

  • 后端

    • Spring Boot 3 升级：3.5.7 -> 3.5.11
    • Spring Boot 4 升级：4.0.3
    • Springdoc 升级：2.8.14 -> 2.8.16（Spring Boot 3）
    • Springdoc（Spring Boot 4）：3.0.2

  • 前端

    • 降级 @types/node 至 22.16.0

v1.1.7 (2026-02-28) ​

新增功能 ​

  • 后端（网关聚合与 context-path 自动发现）

    • 新增微服务 context-path 自动发现能力，支持从注册中心 metadata 解析 nextdoc4j.context-path 等 key，并将服务 context-path 自动拼接到聚合文档地址
    • 在 starter 侧新增 context-path 元数据发布机制，自动将 server.servlet.context-path 注入服务注册 metadata，保证网关可感知
    • 增强网关文档改写能力，统一合并全局安全配置并修正 OpenAPI servers.url

  • 前端（微服务聚合文档）

    • 新增聚合模式的服务选择器、服务菜单与动态路由生成能力，支持按服务维度浏览文档
    • 新增聚合模式下 OpenAPI 数据缓存、标签页状态记忆与服务切换状态管理，减少重复请求
    • 新增服务状态探测与容错切换能力，提升聚合模式稳定性

  • 前端（交互能力）

    • 新增请求参数 Content-Type 设置与处理能力，支持更完整的请求体调试
    • 新增复制 baseUrl 与 path 功能，提升在线调试效率
    • 新增菜单图标组件与图标渲染支持
    • 实体模型菜单新增 JSON 示例视图，并优化实体属性展示

功能优化 ​

  • 后端

    • 将 Swagger URLs 刷新改为异步触发（路由刷新/心跳/请求前），优化网关与微服务启动时序下的数据一致性
    • 优化服务上下文路径解析策略（注册中心、路由 metadata、本地缓存协同），提升重启场景下的更新及时性
    • 精简文档响应重写过滤器，移除冗余逻辑与无用方法，统一路径处理常量并完善代码注释规范

  • 前端

    • 优化网关聚合数据缓存与访问逻辑，简化 getServiceData 调用参数
    • 优化响应体解析流程，增强多内容类型渲染能力
    • 优化 Markdown 预览与目录交互体验
    • 优化请求体内容类型推断与参数表展示
    • 优化菜单 SVG 图标格式与颜色使用，并清理无用 SVG 资源
    • 优化折叠菜单文字与子菜单标题显示

BUG 修复 ​

  • 后端

    • 优化上下文路径元数据处理与过滤器参数注解，提升兼容性与空安全

  • 前端

    • 适配聚合模式下在线测试功能，修复服务切换后的调试请求问题
    • 修复数组类型 items 引用 Schema 的解析问题
    • 修复全局认证样式无法折叠问题
    • 修复 icon 组件在响应式场景下的图标名称解析问题
    • 修正 Markdown 解析器配置，允许原始 HTML 渲染
    • 修复请求体内容类型与表单参数处理的异常场景

v1.1.6 (2026-01-12) ​

新增功能 ​

  • 后端（版本号提供器）

    • 新增版本号提供器，支持从属性文件、Manifest 等多种来源读取版本信息
    • 在 OpenAPI 扩展字段中新增版本号字段，统一版本号注入机制

  • 后端（网关聚合插件）

    • 新增网关聚合文档插件，实现 Spring Cloud Gateway 文档聚合功能
    • 支持路由包含及排除策略，灵活控制聚合范围
    • 支持多种策略解析文档路径与显示名称
    • 支持自动发现和手动配置两种方式提供 Swagger URL
    • 提供丰富的配置选项，包括路由过滤、名称解析、文档路径策略等

功能优化 ​

  • 后端

    • 优化扩展配置加载逻辑，分离基础信息与扩展配置
    • 统一网关插件接口命名规范，提升扩展一致性
    • 精简配置属性结构，优化代码逻辑
    • 优化模块间依赖关系，移除冗余依赖声明

  • 前端

    • 首页版本号改为从后端读取，移除对前端构建版本的依赖

BUG 修复 ​

  • 前端
    • 修复枚举值为 0 时被过滤的问题 (#13)

v1.1.5 (2025-12-22) ​

新增功能 ​

  • 前端
    • 新增响应数据加载中状态反馈，提升用户等待体验

BUG 修复 ​

  • 后端（认证过滤）
    • 修复注销请求判断的逻辑错误，移除错误的 HttpUtil 导入，改用 Spring Framework 的 HttpMethod 进行请求方法比较

v1.1.4 (2025-12-19) ​

新增功能 ​

  • 前端
    • 新增应用版本号显示功能，提升用户体验
    • 新增请求发送按钮加载状态，防止重复点击
    • 新增 JSON 视图复制功能，支持将编辑器内容复制到剪贴板

功能优化 ​

  • 前端

    • 优化测试请求参数编辑器高度自适应逻辑，设置默认高度 500 像素，避免内容少时高度过低

  • 后端（Sa-Token 插件）

    • 优化路径排除器实现，通过 SpringUtil.getBean() 延迟获取替代构造函数注入
    • 解决用户自定义多个 RequestMappingHandlerMapping Bean 时的注入冲突问题
    • 降低 AutoConfiguration 与实现类的耦合度

BUG 修复 ​

  • 前端
    • 修复 format-left 图标填充颜色显示问题，确保图标颜色正确继承父元素颜色

v1.1.3 (2025-12-18) ​

新增功能 ​

  • 后端（认证展示插件）

    • 新增接口认证信息展示插件，支持 OpenAPI Security 元数据统一解析和展示
    • 新增 Sa-Token 适配模块，实现权限、角色及忽略规则注解的解析与展示
    • 支持全局和接口级别的鉴权配置，自动注入 OpenAPI 鉴权信息
    • 引入路径排除机制，基于注解动态排除特定接口的鉴权

  • 后端（枚举解析）

    • 新增枚举展示解析，支持自定义枚举接口类型及方法名
    • 支持基于反射调用自定义的枚举值和描述方法
    • 统一解析流程，增强了扩展性和灵活性

  • 前端

    • 新增认证展示组件，支持 API 访问权限及权限要求明细展示
    • 增强枚举展示功能，支持枚举描述展示，格式( 1 - 启用 , 0 - 未启用 )
    • JSON 查看器、参数视图、模式视图组件均支持扩展枚举信息展示

BUG 修复 ​

  • 前端
    • 修复 JSON 节点复制功能异常问题

v1.1.2 (2025-12-08) ​

新增功能 ​

  • 后端（枚举插件）

    • 实现枚举插件自动配置，基于 SpringDoc 与配置属性自动启用
    • 支持通过配置控制插件启用、描述颜色及枚举展示行为
    • 新增插件相关常量，统一命名空间与插件标识管理
    • 补充自动配置元数据，增强 Spring Boot 自动加载支持

  • 后端（枚举处理能力）

    • 增强枚举参数与模型处理能力，支持参数与模型中的枚举类型完整自定义处理
    • 统一设置枚举类型的 enum 列表、type、format
    • 新增枚举值与描述映射信息追加展示
    • 优化枚举描述 Map 的生成顺序与安全性，确保展示稳定

  • 前端

    • 新增 JSON 复制能力
    • 新增 JSON 字段说明展示
    • 支持渲染 HTML 格式的 API 描述（兼容后端能力增强）

功能优化 ​

  • 后端（枚举插件）
    • 调整为从配置读取描述颜色与展示开关
    • 优化枚举描述与枚举值展示逻辑，支持可控的显示策略

BUG 修复 ​

  • 后端
    • 从 nextdoc4j-core 与 nextdoc4j-dependencies 移除 jackson-databind 冗余依赖
    • 为 NextDoc4jExtensionOpenApiCustomizer 添加 @SuppressWarnings 处理无效警告
    • 清理多余依赖声明，规整 pom.xml 配置
    • 优化枚举参数处理与自动装配逻辑，移除无效注解，并统一注入 ObjectMapper

依赖更新 ​

  • Spring Boot 升级：3.5.5 -> 3.5.7

v1.1.1 (2025-11-13) ​

功能优化 ​

  • 后端

    • 移除 NextDoc4jPathMatcherUtils 中不必要的双重检查锁定，精简逻辑结构，提升执行效率

  • 前端

    • 支持渲染 HTML 格式的 API 描述，丰富接口文档展示能力，提升阅读体验

BUG 修复 ​

  • 前端
    • 修复深色模式下全局认证样式异常问题，统一视觉表现
    • 修复 header / query 参数名与 securitySchemes 定义不一致的问题，保证认证参数解析正确
    • 修复测试按钮未禁用导致的重复点击问题，避免多次请求触发

v1.1.0 (2025-11-05) ​

功能优化 ​

  • 详情页样式重构

    • 重构 API 详情页样式，将请求参数示例与 JSON 示例调整为左右结构分布，优化界面布局与信息可读性（优化前为单栏展示，优化后左右分栏更清晰）

  • 全局认证 UI 重构

    • 全新设计全局认证配置 UI，界面布局更简洁直观，支持多种认证方式的便捷配置与管理

BUG 修复 ​

  • 后端路径过滤问题修复
    • 修复后端路径过滤无法匹配前缀的问题，确保 /xxx/v3/api-docs 等带前缀的路径也能被正确拦截

依赖更新 ​

  • Jackson 升级：2.18.2 -> 2.20.0
  • Spring Boot3 升级：3.5.5 -> 3.5.6
  • Springdoc 升级：2.8.13 -> 2.8.14
  • Hutool 升级：5.8.37 -> 5.8.41
  • Swagger 升级：2.2.36 -> 2.2.39

v1.0.1 (2025-10-17) ​

功能优化 ​

  • 主页配色优化

    • 统一主页配色方案，与全局风格保持一致，提升视觉一致性

  • Spring Boot 适配

    • 自动适配 servlet.context-path，保证在自定义上下文路径下，文档可通过对应路径（如 /app/doc.html）访问

  • 列表解析优化

    • 改进 list 数组类型字段解析逻辑，提升文档展示准确性和可读性

  • 入参字段范围展示

    • 增加入参字段范围信息，更直观体现参数约束

  • 文件上传接口优化

    • 接口在有无 multipart/form-data 声明的情况下，均可展示文件类型信息
    • 优化文件 + 额外参数上传（表单混合提交）的解析和展示

BUG 修复 ​

  • 标题统一性修复

    • 修复主页与左侧菜单栏标题不一致的问题，保证界面风格统一

  • Body 双 JSON 折叠问题修复

    • 修复同一接口返回或请求体包含两个 JSON 时，折叠/展开显示异常的问题

依赖更新 ​

  • Springdoc 升级：2.8.11 -> 2.8.13

v1.0.0 (2025-09-10) ​

新特性 ​

  • 核心适配：深度适配 SpringDoc 与 OpenAPI 3 规范，提供全新现代化文档 UI，替代传统 Swagger UI，优化 API 文档展示与交互体验
  • 配置管理：支持开关配置（可灵活控制文档 UI 功能启用 / 禁用）与生产模式配置（适配生产环境下的文档访问权限与安全管控）
  • 认证功能：新增认证登录模块，保障 API 文档访问安全性，防止未授权用户查看敏感接口信息
  • 品牌定制：支持品牌 logo 与标题自定义配置，可根据团队或项目需求替换默认标识，强化品牌辨识度
  • 登录界面美化：实现动态标题与动态 logo 效果，支持配置化展示，提升登录页面视觉体验
  • 主页优化：同步增加主页动态标题与动态 logo 配置，与登录界面风格保持一致，实现整体视觉统一性

最后更新于: