如何使用 swagger-js 生成静态 HTML 文档？答案

【问题标题】：How to generate static HTML documentation with swagger-js?如何使用 swagger-js 生成静态 HTML 文档？
【发布时间】：2015-09-21 21:31:06
【问题描述】：

我有一个集成了 Swagger 的 RESTful API，因此现在可以使用浏览器指向该服务器并查看记录该 API 的 Swagger UI。我想使用 swagger-js 项目从服务器上的 Swagger 数据生成 Javascript 中的客户端 SDK。

生成此客户端 SDK 似乎可行，我可以在 Chrome 开发人员工具中逐个对象和逐个函数地探索 SDK 对象。不过，我想以某种方式为这个客户端 SDK 生成文档，这样用户就可以阅读它来找到他们想要进行的调用，而无需在浏览器开发环境中费力地探索。

例如，如果我的客户端 SDK 是从 Swagger 数据生成并具有以下方法：

PetStore.addPet(petData)
PetStore.updatePet(petId, petData)
PetStore.deletePet(petId)

我想要用户可以阅读以了解这些的静态文档。这可能吗？

Swagger-codegen 项目有一个开关，可以在使用给定语言制作 SDK 时生成静态 HTML 文档，但奇怪的是它不支持 Javascript，而是将其留给 swagger-js 项目，该项目似乎无法制作静态文档。

【问题讨论】：

【解决方案1】：

查看 [1] jsdoc 以生成自动生成的 javascript 客户端 SDK 的文档。本文档的质量取决于 javascript 代码中的代码 cmets，因此它很可能不是高质量的文档。不过试试看吧。

【讨论】：

这似乎是个好主意，谢谢 Vineet 我明天试试！将报告它与 swagger-js 生成的客户端的工作情况。
它似乎不起作用，因为客户端SDK是在运行时从swagger JSON动态生成的。因此，您永远不会有 SDK 对象的 .js 文件来通过 JSDoc 运行。 swagger-js 项目似乎没有提供静态客户端，我无法通过 JSON.serialize 运行对象来制作文件，因为它们具有循环结构。
是的，抱歉，您可以使用github.com/wcandillon/swagger-js-codegen，它为nodejs 或angularjs 生成javascript 代码。没有用于 swagger 的 vanilla javascript 静态代码生成器。
成功了，谢谢！缺点是它只是 angular，有些客户可能不想使用 angular，但我认为这是目前可用的最佳解决方案。
是的，不幸的是它不是普通的 javascript。 jsdoc 的一种选择是 yuidoc，它有更好看的主题。