You need to enable JavaScript to run this app. Spring Boot 2.4.0环境下Spring Rest Docs自定义snippets被忽略问题
优惠活动
大模型
产品
解决方案
定价
更多

Spring Boot 2.4.0环境下Spring Rest Docs自定义snippets被忽略问题

Spring Rest Docs自定义snippets失效问题排查

基础运行环境

  • 开发工具:IntelliJ IDEA 社区版
  • 基础框架:Spring Boot 2.4.0
  • 集成组件:Spring Rest Docs

问题表现

这套Spring Rest Docs配置在其他所有服务项目中均可正常生成接口文档,仅单个项目出现所有自定义snippets加载不生效的问题。
为了定位问题,以http-request自定义片段为验证对象开展测试:

  • 按照官方规范放置模板文件:路径为src/test/resources/org/springframework/restdocs/templates/asciidoctor/http-request.snippet
  • 模板内容为:
[source,http,options="nowrap"]
----
{{method}} {{path}} HTTP/1.1
----
  • 预期效果:生成的http-request文档片段不包含请求体内容
  • 实际效果:生成的文档仍然保留默认的请求体部分,所有自定义snippets均未生效

初步排查动作

  • 断点调试StandardTemplateResourceResolver类,确认自定义模板完全没有被识别
  • 按照类的设计逻辑,getFormatSpecificCustomTemplate方法本应可以正常解析到对应自定义snippets,但实际运行时未匹配到对应资源
  • 一度怀疑是新增资源目录时遗漏了类路径相关配置,导致资源无法被框架扫描

根因定位

直接打开本地文件管理器查看src/test/resources目录的物理实际结构,发现操作失误:

创建自定义模板目录时,本该逐层创建嵌套的org、springframework、restdocs、templates、asciidoctor多级子目录,实际创建了名称包含完整目录层级字符串的单个文件夹。

由于IntelliJ IDEA的项目视图会自动将带路径分隔符的文件夹名称渲染为嵌套目录结构,IDE界面显示的目录结构和正常多级嵌套结构完全一致,但实际物理类路径下的资源结构不符合Spring Rest Docs的模板扫描规则,最终导致自定义snippets无法被加载。


内容的提问来源于stack exchange,提问作者FishingIsLife

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.12 15:27:01