提供Node / JS REST API的文档
我正在寻找使用Node和Express构buildREST API，并且希望为它提供文档。 我不想手工制作，看起来有Swagger，RAML和Api Blueprint / Apiary等forms的解决scheme。
我真正喜欢的就是使用Swabbuckle或者微软提供的解决scheme，尽可能在.NET中使用API代码自动生成文档，但是通过强大的input和reflection使得它们成为可能。
对于JS世界来说，正确的select是使用Swagger / RAML / Api Blueprint标记来定义API，然后从中生成文档和脚手架服务器。 前者看似简单，但我对后者不太确定。 我所见过的所有这些选项的服务器代码生成看起来都非常有限。 需要有一些方法来将自动生成的代码与手动代码分开，以便定义可以很容易地更新，而且我也没有看到任何迹象或讨论。 这似乎不是一个不可逾越的问题（我比.NET更熟悉.NET，所以我可以很容易地错过了一些东西），并提到这个问题和解决scheme正在从以前的堆栈溢出问题一年前。
任何人都可以告诉我，如果我失踪/误解任何东西，如果有解决上述问题的存在？
我对API和dynamic语言的使用经验是重点在于validation，而不是代码生成。
例如，如果使用编译语言，我会根据API规范生成工件，并使用它来执行正确性。 通过生成接口而不是具体的类来支持往返跳闸。
使用dynamic语言，规范在testing时使用，以保证所有定义的API都是testing覆盖的，并且响应符合规范（由于Postel定律，我倾向于不validation请求，但也可能） 。
swagger-node-express的最初版本就是这么做的 – 你可以从路由，模型等等中定义一些元数据，文档会自动从中产生。 鉴于javascript是如何dynamic的，对于很多用户来说，这变得有点麻烦，因为它要求你保持元数据与模型的更新有些分离。
快进和最新的swagger-node项目采取了一种替代方法，可以考虑在某种意义上与“从代码生成文档”一致。 在这个项目中（对于java来说， swagger-inflector和用于python的connexion ）采用swagger规范是 api的DSL的方法，而路由逻辑则由swagger文档中定义的内容来处理。 从那里，你只需要实现控制器。
如果你把swagger规范看作“像代码一样”，那么这是一个非常有效的方法 – 文档从字面上看不会过时，因为它用于构造所有路由，validation所有inputvariables，并将API连接到您的业务层。
虽然真正的代码生成（例如swagger-codegen项目中的可用代码）非常有效，但在初始构build服务器之后 ，它确实需要与您的代码进行巧妙集成。 以上三个项目的工作stream程完全没有考虑到这一点。
我希望这是有帮助的！