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