您如何记录REST API的使用/消耗？

Question

我们有一个中等大小的应用程序（100多个SQL表），我们经常需要将其与合作伙伴API集成在一起（以我们的系统作为客户端/消费者）。设计此类集成的过程并非易事：

• 我们经常需要将数据库中的列映射到对合作伙伴API的请求中的字段。
• 对合作伙伴API的请求中的某些字段必须是恒定的或有条件的
• 在极少数情况下，一个API响应的输出会成为另一个API请求的输入

网络上有很多资源可用于记录REST API-有特定的格式（Swagger，RAML等）。这些格式允许高效生成客户端代码和人类可读的文档。但是，这些格式对于描述应用程序如何与API集成不是很有帮助。我们创建了冗长的Microsoft Word文档，其中包含或多或少的合作伙伴API方法的副本，并附有应如何使用每个单独字段的注释。这种解决方案似乎不是最优的。

使用Google搜索更好的选项并不会产生很多结果，即Swaggerhub似乎具有“注释”功能，该功能似乎针对上述问题，仅此而已。

问题：是否有一些工具，格式，工作流，想法等可用于设计和记录上述API集成？

Answer 1

我不知道您使用哪种语言，但我使用的是ApiDoc

https://apidocjs.com/

他非常适合在NodeJS中生成带有注释的API REST文档，他可以使用多种语言