如何在Apiary Blueprint中维护API版本历史并实现版本选择下拉功能

Apiary Blueprint本身没有原生支持直接维护API版本历史，也无法自动读取Git分支/标签生成带版本选择的下拉菜单（类似Angular文档的"Doc Versions"功能）。不过可以通过以下几种方式实现类似需求：

1. 手动维护独立版本项目 #

• 在Apiary中为每个API版本创建单独的文档项目，比如命名为my-api-v1、my-api-v2。
• 在主文档页面添加手动维护的版本链接列表（用Markdown列表即可，若需要更接近下拉的样式，可嵌入简单自定义HTML），引导用户跳转对应版本的文档。
• 每个Apiary项目对应Git仓库里的特定分支或标签，发布新版本时同步更新对应项目的Blueprint内容。

2. 结合Git与自动化脚本 #

• 编写脚本监听Git的分支创建或标签打标操作，当有新的版本标签（如v1.0.0）或分支时，自动将对应版本的Blueprint文件同步到Apiary的对应项目。
• 借助Apiary的官方API完成文档项目的创建或更新，然后在主文档中维护版本链接列表（Apiary本身不支持动态生成下拉，需手动或通过脚本预先生成链接）。

3. 切换到原生支持多版本的工具 #

如果需要开箱即用的版本下拉菜单和Git集成，建议考虑替代工具：

• 使用GitBook或Read the Docs搭配API Blueprint渲染器，这类工具原生支持基于Git分支/标签的版本管理和下拉选择。
• 采用Swagger UI配合版本化的OpenAPI规范，通过配置实现多版本切换。

简单来说，Apiary本身做不到Angular文档那样的原生版本切换体验，但通过手动维护或自动化手段，能间接实现多版本文档的访问功能。

内容的提问来源于stack exchange，提问作者Sadiq Khoja