Apiary 即将关闭。Oracle 已发布了终止 Apiary 支持的公告，而 API 工具领域的各类报道指出，该托管服务最终将于 2026 年 9 月左右彻底关闭。尽管该网站目前仍能打开，但其发展轨迹早在多年前就已清晰：Oracle 于 2017 年 1 月收购了 Apiary，在 2018 年废弃了付费方案，并任由其周边的开源工具（Dredd、Gavel）逐渐进入归档状态。如果您的接口文档仍托管在 apiary.io 上，那么您现在面临的已不再是“评估替代方案”，而是必须进行迁移，并且这个截止日期是无法更改的。
明确的结论是：Apifox 是最佳的 Apiary 替代方案。因为它不仅完全替代了 Apiary 的所有功能（基于文档模式的规范编辑、托管的交互式文档、mock 服务端），还补充了 Apiary 从未完善的部分：自动化 API 测试、用于取代已归档 Dredd 的规范驱动校验，以及 CI 集成。它可以免费供最多 4 位用户使用，付费方案起售价为每位用户每月 9 美元。唯一需要注意的限制是，Apifox 无法直接导入 API Blueprint 文件，因此基于 Blueprint 的项目在迁出时需要进行一次性的 OpenAPI 格式转换。本文将介绍 Apiary 当前的状况、包含上述转换步骤的详细迁移路径，以及在 Apifox 不适合您时有哪些其他替代方案。
Apiary 究竟发生了什么
成立于 2011 年的 Apiary 作为一款产品，实际上开创了以文档模式为核心的 API 工作流（design-first API workflow）。它向世界推出了 API Blueprint（一种在 OpenAPI 普及前基于 Markdown 的 API 描述格式），以及由 Stripe 推广并被所有人效仿的三栏式文档布局。它还集成了托管的 mock 服务端、GitHub 同步以及两个备受欢迎的开源契约测试工具：Dredd 和 Gavel。
随后 Oracle 在 2017 年 1 月将其收购，该产品便进入了漫长的沉寂期。付费方案在 2018 年被废弃，使得 Apiary 成为一个免费的遗留服务，而 Oracle 则引导企业客户转向其 API Platform Cloud。新功能的开发随之停止，Dredd 和 Gavel 被归档。现在迎来了正式的终结：Oracle 发布了终止支持公告，托管服务预计将在 2026 年 9 月左右彻底关闭。发布迁移指南的厂商之一 Bump.sh 在其告别贴中直言不讳地指出：请在关停前导出您的 API 描述，因为关停之后将没有任何数据可供导出。
这会带来两个实际的后果。首先，任何仅存在于 Apiary 内部的内容（接口定义/规范、文档内容、团队配置）现在都需要导出，趁着导出按钮还能正常工作。其次，由于 API Blueprint 没有得到维护的后续工具，这次迁移也是一次格式迁移：无论你最终选择哪个平台，最合理的迁移目标格式都是 OpenAPI。
你需要替换什么
明确 Apiary 到底为你的团队提供了哪些功能是非常有帮助的，因为替代方案必须涵盖每一个部分：
- 文档模式的规范编辑器。 你在浏览器中编写 API Blueprint（或在后来的项目中编写 OpenAPI 3.0），文档会实时更新。
- 托管的交互式文档。 带有示例请求的三栏式参考文档，托管在 apiary.io URL 上。
- mock 服务端。 每个 Apiary 项目都会获得一个托管的 mock 接口，该接口根据你的接口定义/规范提供示例数据，以便调用方可以在后端开发完成之前进行对接。
- GitHub 同步。 接口定义/规范文件保存在你的 GitHub 仓库中，并进行双向同步。
- 通过 Dredd 进行契约测试。 这是一个开源的 runner，它会针对实际实现重新运行你的接口定义/规范并报告偏差。它目前已被归档；我们在“如何在没有 Dredd 的情况下根据接口定义/规范校验你的 API”中探讨了替代方案问题。
这一整套功能（设计、文档、mock、校验）正是现代 API 开发平台的基本形态。这就是为什么最佳的迁移目标不是一个单纯的文档渲染器，而是一个具有相同形态且在持续活跃开发中的平台。
解决方案：Apifox
Apifox 是一个被超过 50 万开发者使用的 API 开发平台。它涵盖了 Apiary 在 2011 年构想但后来停止构建的完整生命周期：设计、文档、mock、调试和自动化测试，所有这些都由同一个接口定义/规范驱动。
对于特别需要从 Apiary 迁移的用户来说：
- 文档模式是默认的工作流。 Apifox 拥有针对 OpenAPI 3.x 的可视化接口定义编辑器和代码编辑器。您只需定义一次接口、数据模型和示例；文档、mock 和测试都会作为该定义的生成视图呈现，这与 Apiary 开创的理念相同，并且背后有一个持续维护的产品作为支持。
- 文档是托管的、交互式的，并且归您所有。 发布后的文档将采用现代参考布局，配有可运行的“try it”控制台、自定义域名以及版本控制。无需担心因平台关闭而丢失 apiary.io 的 URL。
- mock 服务端比您即将弃用的那个更智能。 Apiary 的 mock 只是重放您编写的示例。而在 Apifox 中，一旦接口定义存在，智能 mock 就会立即根据您的数据模型生成逼真的响应，无需任何示例，并且您还可以在需要确定性的地方添加自定义 mock 规则。
- 契约验证替代了 Dredd。 Apifox 的自动化测试场景会对您的实现运行真实的请求，并根据接口定义的数据模型验证响应，这正是 Dredd 过去所做的工作，此外还支持断言、数据驱动用例以及通过 Apifox CLI 进行 CI 运行。文档还可以与 MCP 服务端一起发布，以便 AI 智能体（Agent）可以直接读取您的接口定义；详情请参阅“什么是 Apifox MCP 服务端”。
从 Apiary 迁移的逐步指南
与常规的工具切换相比，此次迁移多出了一个额外的步骤，最好提前说明：根据 Apifox 导入文档，Apifox 支持导入 OpenAPI (Swagger 2.0, OpenAPI 3.0 和 3.1)、Postman 集合、HAR、RAML、JMeter、apiDoc、I/O Docs、WADL 以及 Google Discovery。但 API Blueprint 不在此列表中，因此 Blueprint 项目需要先转换为 OpenAPI。在实际操作中，这只是一个一次性的命令，也是任何其他主流迁移目标所要求的相同步骤，因为现在已经没有人再维护 Blueprint 工具链了。
1. 立即从 Apiary 导出所有内容
对于每个项目，从 Apiary 编辑器下载 API 描述。如果项目与 GitHub 同步，那么您的单一事实来源（source of truth）已经存在于代码仓库中，只需确认它是最新的即可。后来用 OpenAPI 3.0 编写的 Apiary 项目已经处于正确的格式，可以跳过第 2 步。在动其他任何东西之前，请先完全做好这一步：导出是有截止期限的步骤。
2. 将 API Blueprint 转换为 OpenAPI
使用以下维护中的转换器之一：
api-spec-converter(LucyBot)，可直接处理 API Blueprint 到 OpenAPI 的转换apib2swagger，一个专注于 Blueprint 到 Swagger/OpenAPI 的转换器- 随后使用
openapi-format（如果您想规范化输出并将其升级到 OpenAPI 3.1）
然后对结果进行 Lint 检查（可以使用类似 vacuum 的验证器，或工具链中的任何 OpenAPI Linter），并手动检查两个已知的薄弱环节：一个是鉴权方案（由于 API Blueprint 从未对其进行正式建模，因此转换器无法完全恢复），另一个是原本存在于 Blueprint 的 Markdown 章节中而非接口描述中的任何纯文本说明。每个 API 预留一小时的预算即可，不需要一周；因为这只是 Markdown 格式，没有什么玄妙的魔法。
3. 导入至 Apifox
进入项目设置，选择手动导入，选择您的 OpenAPI 文件（或从 URL 导入）。接口、数据模型（schemas）和示例在导入后即呈结构化和分组排列。参考文档立即可用，且无需额外设置，智能 mock 服务端就已针对每个导入的接口生效，这重新实现了 Apiary 曾为您提供的“面向消费者的 mock URL”功能。
4. 重建 Apiary 无法实现的部分
将自定义域名指向您发布的文档，这样下一次任何平台的停机（无论是谁的平台）都无法带走您的文档 URL。将您的 Dredd 检查重建为 Apifox 测试场景：包含真实请求、针对规范的数据模型校验，并支持在本地或通过 CLI 在 CI 中运行。如果您的团队有依赖 Apiary mock URL 的消费者，请在发送通知文档迁移的邮件中，一并附上新的 mock 前置 URL。
单个 API 项目的迁移（包括转换）在一下午内即可搞定。而包含十几个 Blueprint API 的项目集迁移则需要一个迭代的时间，其中大部分时间主要用于鉴权方案的手动检查。
Apiary 与 Apifox 对比一览
| | Apiary（现状） | Apifox | |---|---|---| | 未来展望 | 即将关闭；停止支持，预计服务将于 2026 年 9 月左右结束 | 积极开发中 | | 规范格式 | API Blueprint，后期支持 OpenAPI 3.0 | OpenAPI 3.x（支持 Swagger 2.0 导入），可视化 + 代码编辑器 | | 托管文档 | 是，基于 apiary.io URL | 是，支持自定义域名、版本控制和调试（Try-it）控制台 | | mock 服务端 | 重放已编写的示例 | 感知数据模型的智能 mock 以及自定义规则 | | 契约测试 | Dredd（已归档） | 内置测试场景、数据模型校验、通过 CLI 实现 CI | | 自动化测试套件 | 否 | 是，可视化场景、数据驱动、无限次运行 | | GitHub 同步 | 是 | 支持从 URL 或文件导入/同步规范；基于分支的版本控制 | | 价格 | 免费（2018 年已废弃付费计划） | 最多 4 名用户免费，超出后每人每月 9 美元 | | 导出路径 | API Blueprint / OpenAPI 下载 | 导出为 OpenAPI、Markdown、HTML |
替换免费工具的成本
Apiary 的免费价格是其最具吸引力的遗留特性，因此对于迁移团队而言，公平的对比是计算目标平台的年账单。以官方标价为例：Apifox 4 名用户以内免费，超出后每人每月 18 元；SwaggerHub Team 为每人每月 34.44 美元；ReadMe Pro 为每月 250 美元（按年计费）：
坦白说：如果您只需要一个免费渲染单个规范的地方，许多仅限文档的工具也提供免费额度，只有当您需要 mock 服务端、测试和协作（这些正是 Apiary 最初的核心价值所在）时，上表才具有参考意义。Apifox 的免费计划支持最多 4 名用户，涵盖了所有这些功能。对于许多 Apiary 难民来说，这意味着迁移成本仅仅是一个下午的转换工作。
如果 Apifox 不适合您
这是一个坦诚的章节，因为“继续使用 Apiary”已不再是一个可选项：
- 您只需要文档渲染，别无他求。 如果您的规范是在其他地方生成并测试的，而您纯粹需要带有变更日志工具的精美托管文档，那么像 Bump.sh 这样文档优先的产品（他们为 Apiary 用户提供的迁移指南确实很棒）是一个不错的选择。不过，您仍然需要将 Blueprint 转换为 OpenAPI 才能实现这一目标。
- 您正在标准化 SmartBear 技术栈。 SwaggerHub 是在理念上与 Apiary 的托管规范注册表最接近的继承者。请注意其按席位计费的成本和按次计量的测试执行；我们在关于最佳 SwaggerHub 替代方案中对此进行了详细拆解。
- 您的工作重心是大型平台团队的设计治理。 Stoplight 构建了深度的风格指南和治理工具；在您做出决定之前，可以查看最佳 Stoplight 替代方案，了解它们的对比情况。
- 您对 API Blueprint 存有感情。 虽有同感，但请放手吧。该格式的工具已无人维护，创建它的公司即将关闭，OpenAPI 已经胜出。只需转换一次，从此便可一劳永逸。我们以前关于 API Blueprint 的指南可以作为历史资料来阅读。
常见问题解答
Apiary 到底什么时候关闭？
甲骨文（Oracle）已在其论坛上宣布终止对 Apiary 的支持，目前来自 API 工具厂商的报告显示，该托管服务将于 2026 年 9 月左右关闭。更稳妥的假设是：立即导出，因为该产品的各个部分已经无人维护。
Apifox 可以直接导入 API Blueprint 文件吗？
不可以。Apifox 支持导入 OpenAPI/Swagger、Postman、HAR、RAML、JMeter、apiDoc、I/O Docs、WADL 以及 Google Discovery 格式。请先使用 api-spec-converter 或 apib2swagger 等工具将 API Blueprint 转换为 OpenAPI，然后导入转换后的结果。这是一个一次性的步骤，之后请手动检查身份验证方案。
替代 Apiary mock 服务端的方案是什么？
Apifox 内置的智能 mock 服务端。Apiary 只是重放您编写的示例，而 Apifox 则会自动根据您的数据模型生成真实的响应，并且您可以为特定情况定义自定义 mock 规则。每个导入的接口都无需配置即可获得一个 mock 接口。
替代 Dredd 进行契约测试的方案是什么？
Apifox 的自动化测试场景：它们向您的实现发送真实请求，并根据规范的数据模型校验响应，同时支持通过 Apifox CLI 进行断言和 CI 执行。这不仅涵盖了 Dredd 的工作，还提供了 Dredd 从未具备的测试套件功能。
Apifox 对小团队真的是免费的吗？
是的。免费计划支持最多 4 名用户，包含规范编辑器、已发布的交互式文档、智能 mock 服务端以及 API 测试功能。超过 4 名用户后，费用为每人每月 9 美元，在所有主流的 Apiary 迁移目标中，这是单用户价格最低的。
立即导出，无需重新设计
操作顺序至关重要：首先从 Apiary 导出，然后将 Blueprint 转换为 OpenAPI，最后再从容评估迁移目标，因为前两个步骤有截止时间，而第三个步骤没有。
准备就绪后，将 OpenAPI 文件导入到 Apifox 中，在下午结束前，你就能搭建好文档、mock 和测试套件。下载 Apifox 或在浏览器中开始使用；4 人团队完全免费，而 Apiary 首创的文档模式工作流也终于迎来了一个理应拥有的、得到持续维护的平台。
开发必备：API 全流程管理神器 Apifox
介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。
如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。
值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。
获取专属报价与部署方案
详细的私有化部署系统架构与安全白皮书
针对您公司规模的专属报价单
免费的 1v1 专属产品演示 (Demo) 机会
