如何将Swagger2文档导出为离线可阅读的HTML或Markdown格式？

本文共计1322个文字，预计阅读时间需要6分钟。

网上有很多《使用swagger2构建API文档》的文章，该文档是一个在线文档，需要使用HTTP访问。但在我们日常使用swagger接口文档时，有时需要将接口文档离线访问，例如将文档导出为离线文档。

网上有很多《使用swagger2构建API文档》的文章，该文档是一个在线文档，需要使用HTTP访问。但是在我们日常使用swagger接口文档的时候，有的时候需要接口文档离线访问，如将文档导出为html、markdown格式。又或者我们不希望应用系统与swagger接口文档使用同一个服务，而是导出HTML之后单独部署，这样做保证了对接口文档的访问不影响业务系统，也一定程度提高了接口文档的安全性。核心的实现过程就是：

• 在swagger2接口文档所在的应用内，利用swagger2markup将接口文档导出为adoc文件，也可以导出markdown文件。
• 然后将adoc文件转换为静态的html格式，可以将html发布到nginx或者其他的web应用容器，提供访问（本文不会讲html静态部署，只讲HTML导出)。

注意：adoc是一种文件格式，不是我的笔误。不是doc文件也不是docx文件。