Swagger Editor与Swagger-UI神器使用

  1. 云栖社区>
  2. 博客>
  3. 正文

Swagger Editor与Swagger-UI神器使用

上官瑾文 2017-12-29 19:09:50 浏览3453
展开阅读全文

前言

在没有产品经理或者项目经理的情况下,对于前端和后端打交道来说,无非就是对接口的争争吵吵,字段多多少少的事。大多时候前端都喜欢直接使用后端提供的接口,而后端有时候却不知道前端到底要什么数据,就这样,Swagger这样的神器被我找到了,对于Swagger高级的应用,比如集成到IDE中自动生成文档,今天就不废话了,我主要想说的是怎么用Swagger Editor和UI进行接口对接。

折腾Swagger Editor和Swagger UI

在github上搜索,相信聪明的你肯定能打开这两个神器的资源界面,然后下载,存放目录随便。

下载

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

用git客户端下载其实挺慢的,建议直接下载zip,然后解压就行,速度杠杠滴。

"安装"配置

  1. 我是将两个目录组织在同一个文件夹下了,对于大前端,我们一定会用Node,我用下面的命令初始化了一下这个文件夹(工程)
npm init -y
  1. 将下载的Swagger-editor文件夹拷贝到该工程目录下,并Swagger-ui目录下的dist修改为swagger-ui再拷贝到该工程下面;形成如下目录:



|--swagger
|--swagger-editor
|--swagger-ui
|--node_modules
|--package.json
|-- README.md 


  1. 在swagger根目录执行如下代码
yarn add http-server -D
  1. 修改package.json中的script部分
{
  "name": "yanqiapi",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "./node_modules/.bin/http-server ./swagger-editor -o ",
    "build": "./node_modules/.bin/http-server ./swagger-ui -o"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {},
  "dependencies": {
    "http-server": "^0.10.0"
  }
}

启动swagger-editor

执行如下命令, 不出意外浏览器自动打开http://locahost:8081/, 意外也就是有程序占用了8081端口。

yarn run dev

image

使用需要用到yaml语言,这个语言也比较常用,是一种在xml和json之间转换数据的中间格式;使用场景比如持续集成(CI)traivs就在使用这个语言进行配置测试条件,打开页面后,swagger-editor默认提供了一份.yml的文档,可以看到左边是yaml格式的文档,右边是swagger-editor转换成的接口文档,还是比较清晰的,他的智能提示也是非常人性化的;要学习yaml,直接参考官网就可以了,半小时保证会。

启动swagger-ui

执行如下命令启动swagger-ui;如过8081端口被占用,http-server会自动启动另一个端口

yarn run build

image

打开的这个页面是不是很熟悉,对,就是editor中右边的页面;在真实的环境中,我们会有自己的数据,那怎么实现从editor到ui的数据传输呢?答案就在editor,editor有导出json的功能,而swagger-ui支持yaml转换为json的文件,将其放在和swagger-ui目录下与index.hmtl同一目录下即可。

  1. 导出JSON文件

点击editor导航栏中的File,在弹出的下拉菜单中选择Download JSON,浏览器自动下载由yaml已经转换好的JSON文档

image

  1. 拷贝

将导出的JSON文件拷贝至ui文件夹下,我将其命名为API.json;打开ui下的index.html文件,编辑window.load中的ui.url为API.json,其实对应的是一个路径,可以自己改。

// ...
window.onload = function() {
  // Build a system
  const ui = SwaggerUIBundle({
    url: "API.json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    // ...
  1. 刷新浏览器查看结果

image

  1. 我的成果

image

image
image

总结

swagger-editor和swagger-ui的使用可以说是非常简单,对于在不动手写代码的情况下,前端和后端的沟通就会非常简单有效。对于再开发环境中的配置,这就不涉及了,工具是为了高效工作的,不是折腾的,so..到此为止。

网友评论

登录后评论
0/500
评论
上官瑾文
+ 关注