我有一些私人api用简单的旧快递写的。是时候把它拿出来并提供一些api文档。
我不想(至少还有)重写我的快速应用程序以将api文档集成到代码中。主要是因为我不确定使用什么框架或规范来记录我的api,我真的不想锁定一个特定的东西。
我想在我的api下提供doc作为子资源的一部分(即我不想运行不同的服务器或子域)。也许' / api / docs'。一个加号也可以是我可以嵌入我的应用程序中的UI,可以解析文档,至少在html中提供一个很好的文档演示(api交互是一个加号)。
像swagger-node之类的东西很酷,但需要我重新编写所有快速代码以整合招摇。那时我投入了很大的资金,并且紧紧联系起来。
有没有办法以一种对现有路线微创的方式来提供招摇或碘或或其他东西来记录我的api?
编辑:
我可以用手写的文档提供Swagger规范。我看到的问题是你必须在swagger doc中定义basePath
。这实际上不允许我在不同的域下轻松部署。
答案 0 :(得分:7)
有各种各样的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的疑虑。