微服务的集中式API文档

Question

我和我的团队正在并行构建多个服务。我们从头开始构建所有服务。我希望能够在一个页面/站点中自动显示所有服务的所有API端点。这会有所帮助，因为（除其他外）：

1. 我不必去多个文档网站查看我的整个系统中可用的端点是什么＆＃34;。

2. 确定是否应拆分，组合或简单重构任何服务是一个很好的第一步。

我们的一些服务在Django中，rest-swagger模块是一个很好的帮助。但我不知道如何将来自多个服务的rest-swagger文档合并到一个文档页面/站点中。

我目前正在查看this site以及与Netflix experience相关的任何内容，但无法找到问题的解决方案。也许集中文档在Netflix上并不是600多项服务的重要内容，但这很难相信。

有人可以建议使用工具或方法为微服务架构中的所有服务提供组合的API文档吗？

我改变服务时会发生什么的理想情况：

1. 我点击链接查看我系统中的端点列表。
2. 队友更新服务及其文档。
3. 我刷新了我当前的页面，并且我看到了从第2步开始的更改。

Answer 1

使用我的exp，你有一些路径。

1. http://readme.io/
2. 使用JIRA，Redmine制作维基。
3. 在Github中为独家文档创建一个回购。
4. Google文档。

Answer 2

我不知道任何现有的工具，而只是把我的想法放在哪里做。

从OP描述的内容来看，他们已经在使用Netflix堆栈构建微服务架构。应该有一个存储库来配置每个服务的名称（或URL），“配置服务器”或“服务注册表”将从中读取。对我而言，这是将自己的条目下的每个微服务文档引用的完美位置。这样您就可以在同一个地方维护文档和代码，如果挂钩到配置/注册表服务器，还可能收集实例/连接数等运行时信息。

Answer 3

在类似的情况下，我希望在GIT支持的情况下采用https://readthedocs.org/。