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