我希望使用Node和Express构建REST API，并且我想提供文档。我不想手工制作这个，似乎有Swagger，RAML和Api Blueprint / Apiary形式的解决方案。
我真正喜欢的是在.NET代码中使用Swashbuckle或Microsoft提供的解决方案从API代码自动生成文档，但是通过强类型和反射可以实现这些文档。
对于JS世界，似乎正确的选择是使用Swagger / RAML / Api Blueprint标记来定义API，然后生成文档并从中构建服务器。前者似乎很简单，但我对后者不太确定。我所看到的所有这些选项的服务器代码生成似乎非常有限。需要某种方法将自动生成的代码与手动代码分开，以便可以轻松更新定义，并且我没有看到任何迹象或讨论。它似乎不是一个不可克服的问题（我比.NET更熟悉.NET，所以我很容易丢失一些东西）并且提到了这个问题并且解决方案正在{{3一年多以前。
任何人都可以告诉我，我是否遗失/误解了任何内容，是否存在针对上述问题的任何解决方案？
答案 0 :(得分：4)
swagger-node-express的初始版本就是这样做的 - 您将从路线，模型等中定义一些元数据，文档将从中自动生成。鉴于动态javascript是如何，这对许多人来说变得有点麻烦，因为它要求你以一种稍微脱钩的方式使元数据与模型保持同步。
快进和最新的swagger-node项目采用了另一种方法，可以在某种意义上与“从代码生成文档”一致。在这个项目中（和swagger-inflector用于java，connexion用于python）采用swagger规范 用于api的DSL的方法，并且路由逻辑由在招摇文件中定义的内容。从那里，您只需实现控制器。
如果你把swagger规范视为“代码”，那么这是一种非常有效的方法 - 文档可以永远不会过时，因为它用于构造所有路由，验证所有输入变量，并连接您的业务层的API。
虽然真正的代码生成（例如swagger-codegen项目中提供的内容）非常有效，但它确实需要在最初构建服务器之后与代码进行一些巧妙的集成。通过上述三个项目完全从工作流程中删除了这一考虑因素。
我希望这有用！
答案 1 :(得分：1)
我对API和动态语言的体验是重点在于验证而不是代码生成。
例如，如果使用编译语言，我会从API规范生成工件，并使用它来强制执行正确性。通过生成接口而不是具体类来支持舍入跳闸。
使用动态语言，在测试时使用规范来保证所有定义的API都被测试覆盖并且响应符合规范（由于Postel定律，我倾向于不验证请求，但它是也可能。）