2

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

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

我们希望利用这些工具来创建一个中央模拟服务器和文档公共资源，并且需要处理每个 API 的多个版本的演变。

4

2 回答 2

2

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

以下是我们组织文档的方式。

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

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

  • 认证
  • 项目
    • 项目用户
  • ...
  • 团体
  • 组 v2

现在，每个 API 组都有一个不同的 URL，/v1默认情况下会添加前缀。当我们引入特定 API 的新版本时，我们# Group Groups v2会创建一个以/v2. 这样，我们的用户可以在一页中查看和选择 API 的多个版本。

node 模块的aglio好处是它为 UI 提供了多个主题，提供了一个很好的导航，这样我们的用户就不会觉得页面太重了。在主题中，您可以选择单页 UI 或多页 UI，在选择 API 时，会加载具有相应 API 的页面并更改 URL。

实现这个逻辑非常简单。希望这可以帮助。

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

于 2015-07-01T01:24:50.193 回答
1

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

如果您使用 GitHub 进行版本控制，Apiary 可以连接到 GitHub，您可以设置不同的分支以供 Apiary 中的不同文档选择。

于 2014-08-14T21:34:39.257 回答