如何使用API​​ Blueprint格式最佳地管理版本

Question

人们如何使用API​​蓝图管理多个API版本？

格式似乎不支持单个文件中的版本部分，因此我认为文件名中包含指示符的多个文件是最佳选择。

我们希望利用这些工具来创建中央模拟服务器和doc公共，并且需要处理每个API的不断发展的多个版本。

Answer 1

通过分支管理多个版本对我们来说似乎不方便，因此我们在一个页面中使用多个版本的API呈现整个文档。我们的用户需要只需在网址前加v1或v2即可阅读这两个版本。因此，我们有一个节点应用程序来处理文档请求，并通过aglio节点模块呈现文档。

以下是我们如何组织文档。

1. 用户可以请求/docs/en/spec。
2. en部分决定了文档的语言，因为我们支持不同的语言。
3. 因为整个文档非常庞大，我们会根据蓝图Group（以# Group GroupName开头的内容）将其拆分为文件
4. 当一个请求进来时，我们首先看一下我们之前是否已经编译过doc并且有一个缓存版本，所以我们不会每次都重新编译（这是非常密集的工作，特别是当文档很大的时候）。
5. 如果我们没有缓存版本，我们会读取*.md目录中的所有docs/en个文件。
6. 按字母顺序对文件名进行排序，连接其内容，然后传递给生成aglio内容的html /v1。我们将此内容缓存到一个文件中，然后在每次请求时将其传送到客户端。

UI提供目录（左侧的侧面菜单），例如，具有以下格式。

• 验证
• 项目
  • 项目用户
• ...
• 组
• 群组v2

现在，每组API都有一个不同的URL，默认情况下会附加# Group Groups v2。当我们介绍特定API的新版本时，我们会创建一个新的/v2，其前面加上aglio。这样我们的用户就可以在一个页面中查看和选择多个版本的API。

# Groups节点模块的优点在于它为UI提供了多个主题，这提供了一个很好的导航，以便我们的用户不会觉得页面过载。在这些主题中，您可以选择单页面UI或多页面UI，在选择API时，将加载具有相应API的页面并更改URL。

实现这个逻辑非常简单。希望这会有所帮助。

我们现在正在考虑另一个想法，但还没有开始。这是为了避免将API拆分为不同的aglio，而是修改<system.web>使用的Jade模板，并确保它支持多个版本的开箱即用。

Answer 2

最好在版本控制存储库中对蓝图文件进行版本控制，并将不同的分支视为不同的API版本。您甚至可以在与API服务器实现相同的repo / branch中获得蓝图。

如果您使用GitHub进行版本控制，Apiary可以连接到GitHub，您可以设置不同的分支，以便在Apiary中通过不同的文档获取。