如何将 Swagger 导出为 JSON、Markdown、PDF、Word 文档

Swagger 支持将 API 文档导出为不同的格式,其中包括 JSON 和 Markdown。导出为 JSON 格式可以方便地与其他工具进行集成,而导出为 Markdown 则可以用于生成漂亮和易读的文档。

用 Apifox,节省研发团队的每一分钟

如何将 Swagger 导出为 JSON、Markdown、PDF、Word 文档

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

Swagger 是一个用于设计、构建和文档化 RESTful Web 接口的强大工具。它提供了一个交互式的界面,可以帮助开发人员快速、简单地编写和测试 API。Swagger 还支持将 API 文档导出为不同的格式,其中包括 JSON 和 Markdown。导出为 JSON 格式可以方便地与其他工具进行集成,而导出为 Markdown 则可以用于生成漂亮和易读的文档。


我们以 Swagger Petstore 开源项目为例,将讲述如何从 Swagger 格式的文件转成其它形式的文件,方法不唯一,下面只讲述笔者开发过程中常用的一种方法。

将 Swagger 导出为 JSON

打开 Swagger Petstore 开源项目,点击 swagger.json 文件,鼠标右键,将其存到电脑本地,如下图所示。

Swagger Petstore 开源项目
Swagger Petstore 开源项目
导出 Swagger API 文档为 JSON
导出 Swagger API 文档为 JSON

将 Swagger 文件导入 Apifox

什么是 Apifox?

Apifox 是一个比 Postman 更强大的接口测试工具,Apifox = Postman + Swagger + Mock + JMeter,Apifox 支持调试 http(s)、WebSocket、Socket、gRPC、Dubbo 等协议的接口,并且集成了 IDEA 插件。在开发完接口后,可以通过 Apifox 的 IDEA 插件一键生成接口文档,多端同步,非常方便测试和维护。

Apifox 接口调试界面
Apifox 接口调试界面

Swagger 文件导入 Apifox

打开 Apifox,创建一个项目后,选择“项目设置->导入数据->OpenAPI/Swagger->文件导入”,将上一个步骤已导出的 Swagger 格式的 JSON 文件导入即可。

Swagger 文件导入 Apifox
Swagger 文件导入 Apifox

导入时,会有预览,可以选择导入全部,也可以选择性的导入接口。

Apifox 选择接口文件导入
Apifox 选择接口文件导入

导入成功之后,你可以选择一个环境来测试接口。如下图所示,接口成功返回数据:

Apifox 调试接口
Apifox 调试、管理接口

将文件导出为 Markdown

Apifox 中,选择“项目设置->导出数据->Markdown 格式->导出”,即可将整个 OpenaiAPI 格式(Swagger)的 API 文档以 Markdown 格式导出。

Apifox 导出文件为 Markdown 格式
Apifox 导出文件为 Markdown 格式

Markdown 文件导出后,我们可以看看它是什么样的。如下图所示,包含了目录和基本的 API 请求所需要的数据,整体来看还是非常可观的,点击这里快速体验 Apifox!

Apifox 导出后的 Markdown 文件
经 Apifox 导出后的 Markdown 文件

将 Markdown 转为 PDF、Word 文件

只要文档类型为 Markdown,你就可以转为其它的文件类型,具体如何转换,直接在搜索引擎搜索相关的工具即可。或者使用插件,比如在 Vscode 中,你可以通过 Markdown PDF 这个插件来转换。

在 Vscode 中安装 Markdown PDF 插件
在 Vscode 中安装 Markdown PDF 插件

下载完毕,点击右上角像“一本书加上一个放大镜的按钮”

在 Vscode 中预览 Markdown 文件
预览 Markdown 文件

然后鼠标移动到白色区域,右键选择相应的文件类型导出即可。

在 Vscode 中导出 PDF 文件
在 Vscode 中导出 PDF 文件

总结

跑完一套流程下来,总体上还是可观的,不需要配置太多的东西,也不需要编写代码,简简单单。另外,Apifox 的强大远不止如此,快去体验一下吧!

知识扩展: