OpenSpec 评测：我在 3 个真实 API 上跑了两周，结果是这样的

TL;DR

OpenSpec（openspec.pro / github.com/Fission-AI/OpenSpec）是 Fission-AI 出的 AI API 规范生成工具，可以作为 Claude Code skill 使用
2026 年 4 月，我在 3 个自己的站点 API 上测了两周
简单 endpoint 表现不错——大约 60–70% 的 spec 工作自动完成
复杂业务逻辑、边缘情况、认证流程仍然需要手动写
如果你经常写 API 文档又没有专职技术文档，值得试。只有一个小 API 的话可能用不上

我是谁

我是 Jim Liu，悉尼独立开发者。我做 openaitoolshub.org 和另外 8 个项目——港股数据工具、AI 工具推荐站、几个 Roblox 游戏指南站。

大部分项目都有需要写文档的 API：港股数据接口有 15 个 endpoint，AI 工具推荐 API 有好几个，还有一些内部管理接口。

我给这些 API 写 OpenAPI spec。不算有趣，但是必要的工作，我一直在找一个不用外包就能提速的方法。

OpenSpec 是在 Claude Code Skills 社区里听说的——开发者们把它和 obra/superpowers 并列推荐，说实际在用。于是我决定真正测一下，不只是跑 demo。

OpenSpec 是什么

OpenSpec 是 Fission-AI 出的 AI API 规范生成工具。核心逻辑：你把现有的路由代码指给它，或者用自然语言描述你的 API，它生成一份结构化的规范文档。

可以用 Claude Code skill（从 github.com/Fission-AI/OpenSpec 安装）或者用 openspec.pro 的 Web 界面。Skill 版本集成在 Claude Code 工作流里；Web 版本更独立。

对我来说，Claude Code skill 版本更合适——我本来就在 Claude Code 里工作，代码就在旁边，不想在工具间来回粘贴。

OpenSpec 默认输出 OpenAPI 3.x 格式，也支持更简单的内部 spec 格式，我在两个不需要完整 OpenAPI 合规的项目上用了内部格式。

我具体测了什么

项目 1：LRTS 港股数据 API（15 个 endpoint） 包括 IPO 数据、历史价格、用户投资组合跟踪的接口。复杂度参差不齐——有简单的 CRUD，也有带复杂查询参数和分页逻辑的。

项目 2：openaitoolshub.org 推荐 API（6 个 endpoint） 更简单。4 个 GET 接口形状清晰，1 个 POST，1 个 webhook。这是我预期 OpenSpec 表现最好的地方。

项目 3：内部管理 API（8 个 endpoint） 更复杂——包括认证流程、基于角色的访问控制、还有几个根据用户权限返回不同响应形状的接口。

输出质量——我的实测结论

简单 endpoint：表现稳。openaitoolshub 推荐 API 的 spec，我估计 80–85% 可以直接用。请求格式、响应 schema、endpoint 描述基本准确。花了 20 分钟清理示例、补几个缺失的边缘情况、调整部分描述措辞。和从头写比，省了 2 小时左右。

港股 API 的 CRUD 接口：不错但不稳定。GET/POST/PUT/DELETE 模式和大部分 schema 都对了。分页参数跑了三遍才对——OpenSpec 最初描述基于游标的分页时，技术上是准的，但表述方式会让第一次读的开发者困惑。

认证和权限：这里垮了。管理 API 里根据用户角色返回不同响应体的接口，出来的是没有细节的通用 object 类型。认证流程的描述对已经了解系统的人有意义，但对外部开发者帮助不大。这些部分我最后手动重写了。

边缘情况和错误响应：持续不足。OpenSpec 把 happy path 写得不错。400 带字段级验证消息、403 带具体权限错误码——这些大部分需要自己加。这是 AI 生成 spec 的通用局限：错误处理通常隐含在代码里，需要人的判断才能正确呈现。

安装和工作流

安装 Claude Code skill：

git clone https://github.com/Fission-AI/OpenSpec ~/.claude/skills/openspec

在 Claude Code 会话里，把路由文件放在 context 里：

/openspec src/api/routes/ipo-data.ts

第一次跑 200 行的路由文件花了几分钟。后面对类似文件的运行更快，因为 Claude 在本次会话里已经有了上下文。

有一点值得注意：OpenSpec 对路由文件的处理比对 controller 逻辑更好。如果 endpoint 实现分布在多个文件里，提供路由文件加相关 controller 比只提供其中一个效果好。

openspec.pro Web 界面提供了什么

openspec.pro 界面在编码会话外生成 spec 更方便。粘贴描述、得到格式化的 spec、直接导出。

已经在用 Claude Code 的开发者，skill 版本更实用。不写代码的人（技术文档、PM）想从描述生成 API spec 草稿，Web 界面更合适。

OpenSpec 的不足

条件逻辑对 AI 生成来说很难。 如果你的接口根据输入返回不同形状，OpenSpec 通常挑一条路走，忽略其他分支。这不是 OpenSpec 专有的问题——是 AI spec 生成的共性局限。

示例需要打磨。 自动生成的示例技术上合法，但往往不像 API 在实际中会返回的内容。股价返回 0.00 而不是 238.50。用户 ID 是 "string" 而不是实际 UUID 格式。

读不到认证中间件。 如果认证逻辑在中间件里而不是路由处理函数里，OpenSpec 往往会遗漏或低估安全需求。

多次运行没有状态。 如果你跨多个 Claude Code 会话打磨一个 spec，OpenSpec 不记得你改了什么。每次重新开始。

诚实评价

对于简单 API，OpenSpec 的确能快速搞定 60–70% 的 spec 工作。如果你经常手动写 API 文档，时间节省是真实的——三个测试项目合计我估计省了 3–4 小时。

上限比营销说的低。在复杂的生产 API 上，它替代不了专门的 API 文档工作流。它是处理重复结构工作的初稿工具，不是需要判断力的部分。

我找到的最佳使用场景：在开发新 API 的同时生成 spec 骨架。先用 OpenSpec 搭结构、边开发边同步、最后上线前做一次认真的人工审查。这个工作流实际省下了有意义的时间。

谁适合用 OpenSpec

值得用：独立开发者或小团队，经常写 API 但没有专职技术文档。如果你一年上线 3–4 个新 API，每个花 4–6 小时写文档，OpenSpec 大概能帮你省一半。

可能用不上：团队已有成熟的 API 文档工作流。OpenSpec 生成的内容质量不错，但可能不能干净地集成到现有工具链（Stoplight、Redoc、Swagger UI 编辑器等）。

暂时跳过：有大量条件逻辑、多租户认证、复杂错误分类的企业级 API。这些部分手工投入比能省的多。

FAQ

OpenSpec 免费吗？ GitHub skill（github.com/Fission-AI/OpenSpec）是开源的。openspec.pro Web 界面有免费版和付费版——免费版生成次数有限。

OpenSpec 只生成 OpenAPI spec 吗？ 不是。默认输出 OpenAPI 3.x，也支持更简单的格式。GitHub 仓库的 README 里有可用输出格式列表。

OpenSpec 和 Swagger Codegen 这类工具比怎么样？ Swagger Codegen 从现有 spec 生成客户端代码库。OpenSpec 从代码或描述生成 spec 本身——它是 Codegen 之前的步骤，不是替代品。

对非 JavaScript 的 API 有效吗？ 有效。我测的是 TypeScript/Node.js 代码库。GitHub 仓库里有 Python 和 Go 的示例。输出质量更多取决于你的类型注解是否明确，跟语言本身关系不大。

可以在私有代码库上用 OpenSpec 吗？ Claude Code skill 版本完全通过 Claude Code 标准 API 运行——你的代码不会超出 Claude Code 本身已经看到的范围被发送出去。openspec.pro Web 界面的数据处理方式可能不同，粘贴内部代码前看一下他们的隐私政策。