Swagger工具组件Swagger-editor的介绍及使用

1、Swagger-editor介绍

Swagger-editor 主要用于编写符合 Swagger 规范的 RESTful API 文档，即编写 Swagger 文档。

Swagger-editor 是一个编辑器，可编写 Swagger 文档，来准确描述 API 信息。

Swagger-editor 可采用两种语法风格：

• YAML 语法
• JSON 语法

当然，不使用 Swagger-editor 也可以，你可以使用任何编辑器来编写 Swagger 文档。

2、Swagger-editor 的功能

• 编写 Swagger 文档
• 实时检测 Swagger 文档是否符合 Swagger 规范
• 调试 Swagger 文档里描述的 API 接口
• 转换 Swagger 文档（yaml 转 json，或 json 转 yaml）

可见，Swagger-editor 编辑器比一般的编辑器更适合编写 Swagger 文档。当然 Swagger-editor 的功能还不止上面这些。因此，推荐使用 Swagger-editor。

3、Swagger-editor 的安装和使用

Swagger-editor 有两种方式使用：

• Web 版本的
• Swagger-editor
• 本地的 Swagger-editor

4、Web 版本的 Swagger-editor

Web 版本的 Swagger-editor 直接运行在公网上，Swagger 已经给我们配置好了在线的 Swagger-editor。

也就是说，我们可以直接在浏览器上，访问 Swagger-editor 的 Web 版本来使用它，而无需安装。

用法和本地安装的 Swagger-editor 一样，几乎没有区别。

5、本地的 Swagger-editor

当然，我们也可以不使用 Web 版本的，而是选择自己在本地安装 Swagger-editor。

本地运行 Swagger-editor，需要 Node.js 环境支持。

请确保你的电脑已经安装了 Node.js 。

git clone https://github.com/swagger-api/swagger-editor.git

cd swagger-editor
npm install
npm run build
npm start
123456

注：npm start 命令的作用是在本地启动 http-server，也就是一个 web 服务器。http-server 和 apache、nginx 一样，都是 web 服务器，只不过 http-server 是 Node.js 的内置模块。

推荐单独安装 Swagger-editor。安装完成后，以后想要运行 Swagger-editor，只需切换到 Swagger-editor 的目录，执行下面的命令即可。

npm start
1

启动成功后，就可以通过以下三种方式的任意一种来访问本地安装的 Swagger-editor 。

• http://192.168.10.1:3001
• http://192.168.1.2:3001
• http://127.0.0.1:3001

使用说明

Swagger-editor 分为菜单栏和主体界面两个部分。

Swagger-editor 的界面分为左右两栏，左侧是编辑区，右侧是显示区。

编辑区里默认有一个 Swagger 文档的样例，你可以将其清空，编写自己的 API 描述。

显示区是对应编辑区中的 Swagger 文档的 UI 渲染情况，也就是说，右侧显示区的结果和使用 Swagger-ui 渲染 Swagger 文档后的显示结果基本一致。

Swagger-editor 的菜单栏包含以下几个菜单：

• File： 用于导入、导出、转换、清空 Swagger 文档。
• Edit： 用于转换为标准的 YAML 格式文件，比如删除空白行等。
• Generate Server： 用于构建服务器端 stub 。
• Generate Client： 用于构建客户端 SDK 。