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

Question

我有一些用普通旧快递写的私人api.是时候把它拿出来并提供一些api文档.

我不想(至少还有)重写我的快速应用程序以将api文档集成到代码中.主要是因为我不确定使用什么框架或规范来记录我的api我真的不想锁定一个特定的东西.

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

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

有没有办法服用swagger或iodocs或者其他东西以对现有路线微创的方式记录我的api？

编辑:

我可以用手写的文档提供Swagger规范.我看到的问题是你必须basePath在swagger doc中定义.这实际上不允许我在不同的域下轻松部署.

Answer 1

有很多node.js工具可以将Swagger与你的应用程序集成,我认为它们提供了不同的方法.你可以在这里找到这样的集成列表 - https://github.com/webron/swagger-spec/#nodejs - 但我可以告诉你,还有其他工具没有在那里列出.您可以尝试搜索github以获得swagger和node/express.

至于手动规范和basePath - Swagger 2.0实际上为你解决了这个问题.您可以使用在线编辑器 - http://editor.swagger.io - 以更人性化的YAML表单编写您的规范,然后您可以导出到JSON.与Swagger 1.2和以前的版本不同,basePath现在分为三个属性 - schemes(http,https),host(域,端口)和basePath(应用程序的根上下文).这些属性都不是必需的,并且它们都默认为为swagger.json文件提供的任何内容(规范本身).schemes默认为计划服务swagger.json,host用于服务的swagger.json默认为主机和basePath将\除非明确规定.我相信这应该可以解决您对basePath的担忧.