swagger 基础入门

目录

 

Swagger简介 4

安装 4

1、 Node.js 安装 4

2、 node中http-server安装 4

3、 下载swagger-editor 4

4、 启动 swagger-editor 5

5、 使用浏览器访问http://localhost 5

使用 5

1、 编写API 文档： 7

2、 生成服务端代码： 8

3、 修改&运行服务端： 9

4、 建立&运行客户端： 11

1． 使用swagger-editor 的web 界面： 11

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

3． 使用chrome 的 postman 插件 15

 

 

Swagger简介

Swagger包括Swagger Editor， Swagger UI等不少部分，这里咱们主要讲一下Swagger Editor。它是一个彻底开源的项目，而且它也是一个基于Angular的成功案例。

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

在Swagger UI中，咱们不能进行编写API ，可是咱们能够预览或者测试。

 

 

安装

1、Node.js 安装

swagger 是用node写的，因此须要先按照node。安装nodejs后node和npm会一并安装。

windows 中 直接运行node-v8.1.2-x64.msi 便可完成安装（我已经下载好，位于： \\10.9.60.201\shares\）

 

2、node中http-server安装

任一cmd窗口，执行npm install -g http-server 

 

3、下载swagger-editor

安装swagger-editor 有多种方式，

l 从github 下载安装。 这个方式可能行不通，由于下载一般很慢。

l 从官网下载swagger-editor.zip，解压便可。(已共享)

4、启动 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; 改成本身想要的端口。

 

5、使用浏览器访问http://localhost

结果：

 

 

说明：

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

 

使用

l 示例。

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

  

 

l 设置。

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

 

 

 

1、编写API 文档：

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

几个关键地方须要修改：

• host 改成本地ip:port
• basePath 改成项目名或模块名

•  

 

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

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

 

 

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

 

2、生成服务端代码：

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

 

 

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

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

host: localhost:8080

basePath: /projectABC

以 Swagger Petstore (Simple) 为例， 生成的spring 服务端代码本质上是一个spring-boot 微服务。代码结构以下：

 

3、修改&运行服务端：

l Spring 服务端： spring-server-generated.zip

src\main\java\io\swagger\api包下面的全部Api/ApiController结尾的类须要修改， 如PetIdApi 、 PetIdApiController 中全部的Void 改为 Pet。

ApiController结尾的类的public方法须要完成一些mock操做， 也就是—— // do some magic!

public ResponseEntity<Pet> petIdGet(@ApiParam(value = "ID of the pet",required=true ) @PathVariable("petId") String petId, HttpServletRequest request) {
    // do some magic!

    System.out.println("petId = " + petId);
    Pet pet = new Pet();
    pet.setName("lk 111");
    pet.setBirthday(1234);

    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.TEXT_PLAIN);
    ResponseEntity<Void> responseEntity = new ResponseEntity<>(headers, HttpStatus.OK);

    ResponseEntity<Pet> ok = responseEntity.ok(pet);
    return ok;
}

 

修改完成后双击运行 项目的maven 构建： spring-boot 便可：

 

 

 

因为某些缘由， swagger生成的Spring 服务端代码没有UI 界面， 也就是 没有 swagger-UI。 固然， 只要咱们简单修改，就完成UI 功能：

将swagger-editor-UI.zip（已共享） 放到web根目录，稍做修改便可。

 

l Swagger-editor 生成的nodejs 服务端代码（推荐）， 不用修改就能够直接运行：

解压nodejs-server-server-generated.zip ，  而后cmd 进入nodejs-server-server 目录，npm start 便可运行，访问http://localhost:8080/docs 能够看到swagger-UI ：

 

 

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

 

4、建立&运行客户端：

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

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

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

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

下面分别进行介绍：

1．使用swagger-editor 的web 界面：

举个栗子，咱们如今准备测试GET /pets/{id} ：

右边视图 -> /pets/{id} -> Try this operation , 填好参数，而后点击“Send Request”

 

 

 

 

不过，发送请求进行测试以前，咱们须要作两件事： 

1 因为咱们是在浏览器中进行测试不一样网站的接口。 咱们实际上已经跨域，出于安全缘由，浏览器默认不容许跨域。故咱们须要作一些处理，好比安装一些插件。Chrome 上安装一个Allow-Control-Allow-Origin 拓展：

 

 

 

（chrome 拓展文件为www.cnplugins.com_fhbjgbiflinjbdggehcddcbncdddomop_4_7_2_.crx， 已共享， 若是没法安装， 那么须要从chrome 商店进行下载-安装， https://chrome.google.com/webstore/category/extensions?hl=zh-CN）

 

 

2 因为当前版本的swagger-editor 自己存在一些问题（发送的请求没法设置Content-Type请求头）， 咱们须要修改咱们的后端代码：

src\main\java\io\swagger\api包下面的全部Api结尾的类须要修改，将其中每一个方法的RequestMapping 部分的 consumes 去掉：

 

 

后端代码修改完须要重启。 

处理完毕，咱们就能够进行API 接口测试了：

 

 

 

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

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

 

 

 

因为某些缘由，部分语言可能没法生成代码:

 

 

 

如同swagger-editor生成的服务端代码， 其生成的客户端代码也可能有问题。须要作一些修改：

以生成的java代码为例， 须要将 src\main\java\io\swagger\api包下面的全部Api结尾的类须要修改， 其中的Void 改为 Pet。

src\test\java\io\swagger\client\api 包的类须要修改， 其中的Void 改为 Pet。

 

运行测试方法， 完成测试：

 

 

3．使用chrome 的 postman 插件

下载安装postman，

  

运行：

 

 

 

设置请求头：

 

 

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