功能强大的swagger-editor的介绍与使用

1、Swagger Editor简介

Swagger Editor是一个开源的编辑器，而且它也是一个基于Angular的成功案例。在Swagger Editor中，咱们能够基于YAML等语法定义咱们的RESTful API，而后它会自动生成一篇排版优美的API文档，而且提供实时预览。简单说就是能够边编写API 边预览边测试。

Swagger官方提供了一个Swagger Editor的在线的web版本，http://editor.swagger.io/#/，固然咱们也能够下载到本身的机器在本地运行。

2、Swagger Editor安装

1.Node.js 安装

swagger 是用node写的，因此须要先安装node。安装nodejs后node和npm会一并安装。windows中直接运行node-v8.1.2-x64.msi便可完成安装。

2.node中http-server安装

任一cmd窗口，执行

npm install -g http-server

 

3.下载swagger-editor

安装swagger-editor 有多种方式，

从github 下载安装（有时下载会有点慢）

从官网下载swagger-editor.zip，解压便可。（已共享到QQ群文件：301343109）

3、启动Swagger Editor

在swagger-editor的根目录打开cmd窗口，执行http-server ，默认为8080端口 ，若想更换端口则使用以下命令 http-server –p 80 或者修改：C:\Users\Administrator\AppData\Roaming\npm\node_modules\http-server\bin\http-server 中 84行 portfinder.basePort = 8080; 改成本身想要的端口。

 

使用浏览器访问http://localhost:8080

 

说明：

界面左边是api 文件的 yaml 描述文件， 左边部分能够直接编辑API文档，编辑会当即更新到右边视图。右边是swagger-UI，能够查看文档，并直接进行API的测试。

4、使用Swagger Editor

1.示例

swagger 内置了不少个examples。经过File→Open Example… 打开各示例文档：

 

2.设置

经过 Preference能够进行各类偏好设置：

 

3.编写API 文档

咱们能够参照swagger-editor的示例，直接修改，而后生成本身的文档。

几个关键地方须要修改：

host 改成本地ip:port

basePath 改成项目名或模块名

 

swagger-editor 有自动纠错的功能，编写的API 文档应该保证没有错误。这样才能发布。

编写完毕后， 咱们能够把它保存下来。 可选格式为yaml/json ：

 

固然，咱们也能够把写好的yaml/json 文档导入而后修改、测试。

五、生成服务端代码

Swagger-editor的强大功能，在于其能够生成不少种语言的服务端/客户端代码， 同时服务端代码中包含了Swagger-UI。 以下， 我的认为服务端中 其中 Node.js、Python Flask、Spring 语言的代码比较有价值，值得研究。

 

Spring 服务端代码适合后端开发人员，可是其生成的代码比较简单，并且不能直接使用， 须要作一些修改。

生成代码前， 咱们确保已修改咱们文档的关键地方：

host: localhost:8080

basePath: /projectABC

以 Swagger Petstore (Simple) 为例， 生成的spring 服务端代码本质上是一个spring-boot 微服务。代码结构以下(导入eclipse)（已共享到QQ群文件：301343109）：

六、修改&运行服务端

打开application.properties文件，原来的server.port是8080，我这边有冲突，因此改为8060。

运行Swagger2SpringBoot类的main方法：

 

 看到红色矩形里的文字就表明启动成功了。

 

访问http://localhost:8060/projectABC/swagger-ui.html能够看到swagger生成的api文档了：

 

而后， 咱们就能够进行测试等操做。

七、建立&运行客户端

服务端启动以后， 就能够进行访问测试。访问测试有多种方式，

1 是直接使用swagger-editor 的web 界面

2 是使用swagger-editor生成的客户端代码

3 是使用浏览器插件， 好比chrome 的 postman 插件

下面分别进行介绍：

1．使用swagger-editor 的web 界面

举个栗子，咱们如今准备测试get /estimates/price：

 

2.使用swagger-editor生成客户端代码

swagger-editor能够生成 不少语言版本的客户端代码， 我的认为其中 JavaScript、java 比较有研究价值的，

 

具体参照

swagger-codegen自动生成代码工具的介绍与使用

3．使用chrome 的 postman 插件

下载安装postman

 

运行：

 

设置请求头：

Postman 的具体用法请查看网络相关资料，此处再也不赘述。