需要为使用nodejs/express编写的现有应用程序创建api文档

Question

我有一些用普通老式express编写的私有apis。是时候让它出来了，并提供一些api文档。

我不希望(至少到目前为止)它重写我的express应用程序，以便将api文档集成到代码中。主要是因为我不确定使用什么框架或规范来记录我的api，所以我并不真的想锁定一个特定的东西。

我想作为我的api下子资源的一部分提供文档(即我不想运行不同的服务器或子域)。也许是'/api/docs‘。一个加号也是一个UI，我可以将它嵌入到我的应用程序中，它可以解析文档，至少可以用html提供一个很好的文档演示(api交互性更好)。

像swagger-node这样的东西很酷，但需要我重写所有的快速代码来集成swagger。在这一点上，我有一笔很大的投资，并且与swagger紧密相连。

有没有一种方法可以发布swagger或iodocs，或者其他东西，以一种对现有路由的侵入性最小的方式记录我的api？

编辑：

我可以从一份手写的文档中拿出Swagger规范。我看到的问题是你必须在swagger文档中定义basePath。这并不能让我轻松地在不同的域中部署。

Answer 1

有大量的node.js工具可以将Swagger集成到您的应用程序中，我假设它们提供了不同的方法。您可以尝试在github中搜索swagger和node/express。

至于说明书和basePath -Swager2.0实际上为你解决了这个问题。您可以使用在线编辑器- http://editor.swagger.io -以更人性化的YAML形式编写规范，然后可以将其导出到JSON。与Swagger1.2和以前的版本不同，basePath现在被分成三个属性- schemes (http，https)，host (域，端口)和basePath (应用程序的根上下文)。这些属性都不是强制的，它们都默认为服务于swagger.json文件的内容(规范本身)。schemes默认为方案服务swagger.json，host默认为用于服务swagger.json的主机，除非明确指定，否则basePath将是\。我相信这应该会解决你对basePath的担忧。