1. 项目概述：当Spring Boot遇上AI，如何让Swagger注释“自己写自己”

如果你和我一样，是个常年泡在Spring Boot项目里的Java开发者，那你肯定对Swagger（或者说SpringDoc OpenAPI 3.0）这套东西又爱又恨。爱的是，它生成的API文档清晰漂亮，前后端联调效率直线上升；恨的是，给每个Controller、每个DTO字段手写 @Operation 、 @Schema 这些注释，实在是件枯燥又容易遗漏的体力活。方法名改一下，参数加一个，文档就得跟着改，一来二去，文档和代码不同步就成了常态。

最近在折腾一个内部旅行管理平台，Controller十几个，DTO更是几十个。每次新增或修改接口，补Swagger注释都让我头大。直到我发现了 Cursor IDE 这个“魔法编辑器”和它强大的 Agent 机制，一个念头冒出来：能不能让AI来帮我自动生成和更新这些注释？于是，就有了这个 cursor-openapi-agent 项目的探索和实践。

简单说，这是一个专为Cursor IDE设计的Spring Boot项目增强工具。它的核心工作流非常直观：你写好Java代码（Controller、DTO），它通过静态代码分析（JavaParser）提取出代码的结构化信息，然后调用大型语言模型（LLM）来生成符合OpenAPI规范的、语义化的韩文注释，最后再把这些注释精准地插回你的源代码里。整个过程，你只需要在Cursor里敲两个简单的命令。这不仅仅是“自动生成注释”，更是一种“代码与文档实时同步”的开发体验升级。

接下来，我会带你深入这个工具的内部，拆解它的设计思路、实现细节，并分享我在集成和使用过程中踩过的坑和总结的经验。无论你是想直接使用这个工具来解放双手，还是对如何结合静态分析、LLM和IDE插件开发感兴趣，相信都能有所收获。

2. 核心设计思路：三明治架构与关注点分离

拿到一个需求，我的习惯是先想清楚架构。这个工具的目标很明确： 输入Java源码，输出带Swagger注释的Java源码 。但具体怎么实现，有几个关键问题要解决：

1. 代码信息如何准确提取？ 不能光靠正则表达式去蒙，需要理解Java语法。
2. 注释如何生成？ 需要理解API的语义，生成符合规范且描述准确的文字。
3. 如何与IDE无缝集成？ 要让开发者用起来顺手，而不是脱离开发环境。

这个项目的设计给出了一个清晰的“三明治”架构答案，很好地实践了 关注点分离 的原则。

2.1 架构分层解析

第一层：信息提取层（底层） 这一层的核心是 JavaParser 。它是一个强大的Java静态分析库，能把Java源代码转换成抽象语法树（AST）。工具里的 extractor 模块就是这个层的实现。它的任务很纯粹：像编译器一样读懂你的代码，但不去理解业务逻辑。它会识别出哪些类是 @RestController ，哪些方法是 @GetMapping ，方法的参数是什么类型，返回什么类型，DTO里有哪些字段，字段上有没有 @NotNull 、 @Size 这样的校验注解。然后，把这些结构化的信息（比如类名、方法名、参数列表、字段类型）提取出来，组装成一个JSON文件（ endpoints.json ）。你可以把这个JSON看作一份“代码结构清单”。

为什么用JavaParser而不是反射？ 反射需要编译后的.class文件，而我们的工具需要在编写代码的 过程中 就起作用。JavaParser直接分析源码，不依赖编译，更符合“实时辅助”的场景。

第二层：智能生成层（夹心层） 这是AI发挥作用的地方。工具本身并不包含LLM，而是把第一层生成的“代码结构清单”（JSON）和原始的代码片段，一起提交给Cursor IDE背后的LLM。你可以这样理解：我们给AI提供了一个高度结构化的“上下文”，告诉它“这是一个用户查询旅行详情的GET接口，参数是路径变量tripId，返回一个Trip对象”。然后向AI提问：“请根据这些信息，生成符合OpenAPI 3.0规范的Swagger注解，使用韩语描述。” LLM凭借其强大的代码和自然语言理解能力，就能生成语义通顺、格式正确的注释。这一层的关键在于 提示词工程 ，如何组织输入信息，才能让AI输出最符合我们期望的结果。项目通过预定义的命令模板（ .cursor/commands 里的文件）来封装这个交互过程。

第三层：集成应用层（顶层） 这一层负责把AI生成的“成果”送回去。Cursor IDE的Agent机制允许我们执行脚本并接收AI返回的代码块。 /swg-apply 命令就是干这个的：它读取AI生成的注释建议，并以“代码差异”的形式展示在Cursor的编辑器中。你可以像Review代码一样，逐条接受或拒绝这些修改。这一步至关重要，它保证了 开发者拥有最终控制权 ，AI只是助手，不会擅自改动你的代码。

2.2 工作流设计：精准与高效的平衡

工具提供了两种扫描模式，对应不同的使用场景，体现了对效率的思考：

1. 全量扫描 ( /swg-extract ) ：这是“大扫除”模式。它会遍历整个 src/main/java 目录，找出所有的Controller和DTO。适合项目初期引入Swagger，或者很久没维护文档，需要一次性补全所有注释的情况。虽然耗时可能稍长，但一劳永逸。

2. 增量扫描 ( /swg-extract @FileName.java ) ：这是“精准打击”模式。当你只新增或修改了一个 UserController.java 文件时，你只需要针对这个文件执行提取。工具会智能地分析这个Controller所引用的DTO，并一并提取相关信息。这极大地提升了日常开发的效率，做到了“即改即生成”。

这种设计避免了每次都为整个项目付出计算成本，将资源用在刀刃上，是工具能否融入日常开发流程的关键。

3. 实操部署：两种安装方式与细节剖析

理论说完了，我们动手把它装到项目里。项目提供了自动和手动两种安装方式，我会详细解释每一步背后的意图，帮你避坑。

3.1 自动安装：一键脚本的便利与风险审视

自动安装是最快的方式，只需在Spring Boot项目的根目录下执行一条命令：

curl -sSL https://raw.githubusercontent.com/qlqlrh/cursor-openapi-agent/main/install.sh | bash

这条命令做了以下几件事：

1. curl -sSL ：从GitHub Raw地址安静地（ -s ）下载安装脚本，并跟随重定向（ -L ）。
2. | bash ：将下载的脚本内容通过管道传递给 bash 解释器执行。

执行前你必须明确的几点：

• 信任问题 ：任何 curl ... | bash 命令都存在安全风险，因为你正在直接从网络下载并执行代码。在运行前， 强烈建议 你先用 curl -sSL [url] 把脚本内容下载下来看一眼，检查它做了什么。这是生产环境的基本安全素养。
• 环境依赖 ：脚本会假设你的系统已安装 git 和 java （版本17+）。如果没装，脚本可能会失败。
• 目录权限 ：它会在你的项目根目录创建 cursor-openapi-agent 和 .cursor 文件夹，需要你有写入权限。

脚本内部逻辑拆解： 一个负责任的安装脚本通常会包含以下步骤，你可以对照检查：

1. 克隆仓库 ：将 cursor-openapi-agent 项目克隆到本地一个临时目录或直接到目标目录。
2. 复制命令文件 ：将Agent自带的 .cursor/commands/ 下的 swg-extract.md 和 swg-apply.md 文件，复制到你 自己项目 的 .cursor/commands/ 目录下。这是让Cursor识别自定义命令的关键。
3. 构建提取器 ：进入 cursor-openapi-agent/extractor 目录，执行 ./gradlew build （或类似命令）来编译JavaParser提取器模块，确保 extractor 这个“底层引擎”是可运行的。
4. 设置执行权限 ：给项目内的Shell脚本（如 scripts/run_extract.sh ）添加可执行权限（ chmod +x ）。

3.2 手动安装：完全掌控的进阶之选

如果你对一键脚本不放心，或者想更深入了解项目结构，手动安装是更好的选择。步骤虽然多几步，但每一步你都清清楚楚。

# 1. 克隆项目到你的工作区
git clone https://github.com/qlqlrh/cursor-openapi-agent.git
# 或者直接克隆到你的Spring Boot项目目录内，重命名文件夹
git clone https://github.com/qlqlrh/cursor-openapi-agent.git your-spring-project/cursor-openapi-agent

# 2. 在你的Spring Boot项目根目录创建Cursor命令目录
mkdir -p .cursor/commands

# 3. 复制命令定义文件
cp cursor-openapi-agent/.cursor/commands/* .cursor/commands/

# 4. 进入提取器模块，构建Java应用
cd cursor-openapi-agent/extractor
./gradlew clean build
# 确保构建成功，生成可执行的jar包（通常在 build/libs/ 下）

# 5. 为执行脚本添加权限
cd ../scripts
chmod +x run_extract.sh

关键点解析：

• .cursor/commands 目录的位置 ：这个目录 必须 位于你的 Spring Boot项目根目录 下，而不是 cursor-openapi-agent 文件夹里。因为Cursor是以你打开的项目为上下文来加载自定义命令的。
• extractor 模块的构建 ：这是一个独立的Java Gradle项目。 ./gradlew build 会下载JavaParser等依赖，编译代码，并运行测试（如果有）。确保你的JDK版本是17或以上，否则可能编译失败。
• run_extract.sh 脚本 ：这个脚本是连接Cursor命令和Java提取器程序的桥梁。它负责接收参数（如文件名），调用 extractor 模块打好的jar包，并输出 endpoints.json 。

安装完成后，你的项目结构应该如下所示，界限非常清晰：

你的SpringBoot项目/
├── src/                    # 你的业务源代码
├── cursor-openapi-agent/   # 代理工具本身（像一个独立的SDK）
│   ├── extractor/          # 元数据提取引擎
│   ├── scripts/            # 执行脚本
│   └── ...
├── .cursor/                # Cursor IDE项目级配置
│   └── commands/           # 自定义命令定义文件
│       ├── swg-extract.md
│       └── swg-apply.md
└── pom.xml 或 build.gradle # 你的项目构建文件

4. 核心使用流程：从命令到注释的完整闭环

安装成功，重启Cursor IDE（有时需要重启才能加载新命令），我们就可以开始体验了。整个工作流就像一条流水线。

4.1 第一步：元数据提取 ( /swg-extract )

在Cursor的命令面板（通常用 Cmd/Ctrl + Shift + P 打开）中输入 /swg-extract 。

发生了什么？

1. Cursor会找到 .cursor/commands/swg-extract.md 文件，并执行其中定义的操作。
2. 这个命令的核心是去调用 scripts/run_extract.sh 脚本。
3. 脚本会启动 extractor 模块的Java程序。该程序根据有无传入 @文件名 参数，决定扫描策略。
4. JavaParser开始工作，解析指定的Java文件，生成一份包含所有API和DTO信息的 endpoints.json 文件，保存在 cursor-openapi-agent/out/ 目录下。

重要参数与场景：

• /swg-extract (无参数) ：全项目扫描。适合初始化或大规模更新。
• /swg-extract @UserController.java ：增量扫描。工具不仅分析 UserController.java ，还会通过分析其导入语句（ import ）和方法签名中的类型引用，自动找到相关的DTO类（如 UserDto.java , CreateUserRequest.java ）一并分析。非常智能和高效。
• /swg-extract @UserDto.java @ProductDto.java ：批量扫描多个DTO文件。

实操心得 ：在团队协作中，我建议将 cursor-openapi-agent/out/endpoints.json 添加到 .gitignore 文件中。因为这个文件是临时生成的，且内容会变，纳入版本管理会产生不必要的冲突。每次需要时重新生成即可。

4.2 第二步：注释生成与应用 ( /swg-apply )

提取完成后，在命令面板中输入 /swg-apply 。

这是魔法发生的时刻：

1. Cursor读取 swg-apply.md 命令定义。
2. 该命令会将上一步生成的 endpoints.json 文件的内容，以及所涉及到的Java源代码片段，作为上下文发送给Cursor内置的AI模型。
3. AI模型基于我们预设的提示词（在命令文件中定义），理解代码结构，并生成对应的Swagger注解代码块。
4. Cursor以“代码建议”或“差异对比”的形式，在编辑器中弹出这些生成的注释。 你可以逐行、逐块地查看AI生成的内容，并决定是“接受”还是“拒绝” 。

生成的注释示例与解读： 以项目文档中的 TripCreateRequest DTO为例，AI生成的 @Schema 注解非常专业：

• description : 直接翻译或合理生成了字段的业务含义（如“여행 제목”）。
• example : 提供了一个符合字段类型的典型示例值，这对文档的可读性和Mock数据生成极其有用。
• required : 这个属性不是瞎猜的！它是通过分析字段上的校验注解 @NotBlank 、 @NotNull 智能推断出来的。有校验注解的， required = true ；否则为 false 或省略（默认 false ）。
• maxLength : 同样，从 @Size(max = 100) 注解中提取信息，并映射到OpenAPI的属性上。

这种基于现有代码约束的智能推断，大大减少了人工校对的工作量。

4.3 使用场景策略表

为了更直观，我将不同开发场景下的使用策略总结如下：

开发场景	推荐命令序列	操作解析与意图
新项目接入Swagger	/swg-extract → /swg-apply	初始化全量文档 。首先提取整个项目的API结构，然后一次性生成所有基础注释，快速搭建文档骨架。
新增一个API接口	/swg-extract @NewController.java → /swg-apply	精准增量更新 。只分析新控制器及其关联的DTO，生成针对性的注释，避免无关文件干扰，效率最高。
修改DTO字段结构	/swg-extract @ModifiedDto.java → /swg-apply	局部同步 。更新字段后，重新提取该DTO信息，AI会为新增或修改的字段生成或更新 @Schema 注释。
定期文档维护	/swg-extract → 审查 endpoints.json → /swg-apply	全量审计与更新 。在版本迭代后，运行全量扫描，可以检查是否有遗漏的接口，并统一更新所有注释，保持文档一致性。

5. 深度定制与问题排查指南

工具开箱即用，但了解其内部机制，能让你更好地驾驭它，并解决可能遇到的问题。

5.1 如何理解与定制提取规则？

工具的核心提取逻辑在 extractor 模块中。如果你想让它识别自定义的注解，或者调整信息提取的规则，就需要深入这里。主要关注两个核心类：

• ControllerVisitor.java ：这个类继承了JavaParser的 VoidVisitorAdapter 。它像一个小机器人，遍历AST中的类定义。当它发现一个类有 @RestController 或 @Controller 注解时，就会记录下来，并进一步遍历这个类里的所有方法，寻找 @GetMapping , @PostMapping 等注解，从而提取出API路径、HTTP方法、参数等信息。
• DtoVisitor.java ：同样是一个遍历器，负责识别普通的Java类（通常是模型或请求/响应对象），并收集其字段名、字段类型、以及字段上的注解（如 @NotNull , @Size , @Email ）。

定制举例 ：假设你的项目用了 @ApiOperation （老版Swagger）而不是 @Operation ，你就可以修改 ControllerVisitor ，让它同时识别这两种注解。或者，你想提取自定义的 @BusinessType 注解信息到描述里，也可以在这里添加逻辑。

注意事项 ：修改 extractor 后，必须重新执行 ./gradlew clean build 来编译打包，新的逻辑才会生效。这属于进阶用法，需要对JavaParser有一定了解。

5.2 常见问题排查手册

在实际使用中，你可能会遇到下面这些问题。别慌，大部分都有解。

问题1：命令 /swg-extract 或 /swg-apply 在Cursor中不显示或无法执行。

• 检查点1 ：确认 .cursor/commands 文件夹是否在 你的Spring Boot项目根目录 下，并且里面是否有 swg-extract.md 和 swg-apply.md 文件。
• 检查点2 ：尝试重启Cursor IDE。有时新加的命令需要重启才能被加载。
• 检查点3 ：打开Cursor的命令面板，输入 > （进入命令模式），查看是否有你自定义的命令列表。

问题2：执行 /swg-extract 时失败，提示Java或Gradle错误。

• 检查点1 ：在终端执行 java -version ，确保JDK版本为17或以上。
• 检查点2 ：进入 cursor-openapi-agent/extractor 目录，手动运行 ./gradlew clean build ，观察构建过程是否报错。常见的错误是网络问题导致依赖下载失败，可以配置Gradle使用国内镜像源。
• 检查点3 ：检查 scripts/run_extract.sh 脚本是否有执行权限（ chmod +x ），以及脚本内部的路径是否正确（尤其是Java jar包的路径）。

问题3： /swg-apply 执行后，Cursor没有弹出任何代码更改建议。

• 检查点1 ：确认 /swg-extract 是否成功执行，并生成了 cursor-openapi-agent/out/endpoints.json 文件。文件内容是否为空或格式错误？
• 检查点2 ：检查Cursor的AI模型是否正常工作。可以尝试在Chat面板问个简单问题，测试AI连接。
• 检查点3 ：查看Cursor的“问题”面板或日志，有时会有更详细的错误信息。可能是提供给AI的上下文过长，超出了Token限制（对于大型项目），可以尝试用增量扫描替代全量扫描。

问题4：AI生成的注释内容不准确或不符合要求。

• 原因与对策 ：这是提示词（Prompt）的问题。生成注释的“指令”隐藏在 .cursor/commands/swg-apply.md 文件中。你可以打开这个文件，查看它是如何构造发送给AI的请求的。通常，你可以调整提示词中的描述，例如要求AI“使用中文生成注释”，或者“更注重描述业务逻辑而非技术细节”。 修改这些命令文件是定制AI行为最直接的方式 。

问题5：生成的注释与现有代码格式（如缩进、注解顺序）不一致。

• 应对策略 ：AI生成的代码风格可能与你项目的代码风格规范不符。 /swg-apply 提供的“接受/拒绝”机制就是用来解决这个的。你可以先接受内容，然后利用Cursor的代码格式化功能（或你配置的formatter）统一格式化。更好的做法是，在你的提示词中明确加入代码风格要求，例如“请遵循Google Java Style Guide，注解放在字段上方”。

5.3 性能优化与最佳实践

• 对大项目的处理 ：如果你的项目非常大，一次性全量扫描可能会慢，且生成 endpoints.json 文件巨大，可能导致AI上下文超限。 坚持使用增量扫描（ @文件名 ）是保持流畅体验的最佳实践 。仅为当前正在修改的模块生成文档。
• 版本控制 ：将 cursor-openapi-agent 作为项目的子模块（git submodule）管理，可以方便地同步工具更新。同时，务必将 out/ 目录加入 .gitignore 。
• 与CI/CD集成 ：虽然这个工具主要面向开发时，但你也可以思考：能否在代码合并前，自动检查Swagger注释的完整性？这需要将提取和检查流程脚本化，集成到你的Git钩子或CI流水线中，作为代码质量门禁的一环。

这个 cursor-openapi-agent 项目展示了一个非常实用的方向：将静态代码分析、大语言模型和IDE深度结合，去自动化那些繁琐、重复但又有固定规则的编码任务。它不仅仅是生成注释，更是一种人机协同编程模式的探索。通过将开发者从模板化劳动中解放出来，让我们能更专注于核心的业务逻辑和创新设计。