Springdoc生成OpenAPI规范时如何追溯对应代码位置

不用改Springdoc核心库，利用其原生扩展能力配合编译/运行期元数据采集即可实现，以下是两种落地成本较低的方案：

方案1：运行期动态注入来源信息（无额外构建环节） #

• 核心逻辑：利用Springdoc提供的OpenApiCustomizer扩展点，配合字节码调试符号读取能力，自动为OpenAPI各元素注入来源元数据
• 实现步骤：
  1. 确认Java编译开启调试符号（javac -g参数，Maven/Gradle、IDEA默认均开启），确保字节码中包含类、方法、字段的行号信息
  2. 引入轻量字节码解析依赖（如org.ow2.asm:asm），封装工具方法：入参为Class对象、方法名/字段名，出参为对应元素的类全限定名、源码文件路径、行号
  3. 自定义OpenApiCustomizer实现类并注册为Spring Bean，在customise方法中遍历OpenAPI的所有接口、参数、Schema定义：
     • 接口定义对应到Spring MVC的@RequestMapping/@GetMapping等注解标注的方法，调用工具方法拿到方法行号
     • 请求/响应参数、Schema字段对应到Java方法参数、实体类字段，调用工具方法拿到对应行号
     • 将来源信息写入OpenAPI元素的extensions属性，自定义key如x-java-source，值可存为结构化JSON，示例：

       "x-java-source": {
         "className": "com.example.controller.UserController",
         "filePath": "src/main/java/com/example/controller/UserController.java",
         "lineNumber": 62,
         "elementName": "pageUser"
       }
       

  4. 若需要实现点击跳转IDE，可在扩展字段中补充IDE跳转协议链接，如IDEA的协议格式为idea://open?file={文件绝对路径}&line={行号}，打开链接即可直接定位到对应代码行

方案2：编译期注入来源注解（性能更高、更稳定） #

• 核心逻辑：用APT（注解处理工具）在编译阶段自动采集源码位置信息，写入自定义注解，运行期Springdoc扩展直接读取注解值即可，无需运行时字节码解析
• 实现步骤：
  1. 自定义标记注解如@ApiSource，包含className、filePath、lineNumber三个属性
  2. 编写APT处理器，编译时扫描所有标注了Springdoc相关注解（@Operation、@Parameter、@Schema等）的类、方法、字段，自动填充@ApiSource注解的属性值
  3. 自定义OpenApiCustomizer实现类，遍历OpenAPI元素时直接读取对应Java元素上的@ApiSource注解值，写入OpenAPI的扩展字段即可

注意：可以通过Spring Profile控制OpenApiCustomizer的生效范围，仅在开发、测试环境加载该扩展，生产环境关闭，避免返回的OpenAPI规范携带内部代码信息，同时不影响运行时性能。

两种方案均完全基于Springdoc原生扩展能力实现，不需要修改Springdoc源码，落地成本远低于二次开发Springdoc库。

内容的提问来源于stack exchange，提问作者juan carlos Jj