在没有产品经理或者项目经理的情况下,对于前端和后端打交道来说,无非就是对接口的争争吵吵,字段多多少少的事。大多时候前端都喜欢直接使用后端提供的接口,而后端有时候却不知道前端到底要什么数据,就这样,Swagger这样的神器被我找到了,对于Swagger高级的应用,比如集成到IDE中自动生成文档,今天就不废话了,我主要想说的是怎么用Swagger Editor和UI进行接口对接。
在github上搜索,相信聪明的你肯定能打开这两个神器的资源界面,然后下载,存放目录随便。
git clone https://github.com/swagger-api/swagger-editor.git git clone https://github.com/swagger-api/swagger-ui.git
用git客户端下载其实挺慢的,建议直接下载zip,然后解压就行,速度杠杠滴。
npm init -y
|--swagger
|--swagger-editor |--swagger-ui |--node_modules |--package.json |-- README.md
|--swagger-editor |--swagger-ui |--node_modules |--package.json |-- README.md
yarn add http-server -D
{ "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" } }
执行如下命令, 不出意外浏览器自动打开http://locahost:8081/, 意外也就是有程序占用了8081端口。
yarn run dev
使用需要用到yaml语言,这个语言也比较常用,是一种在xml和json之间转换数据的中间格式;使用场景比如持续集成(CI)traivs就在使用这个语言进行配置测试条件,打开页面后,swagger-editor默认提供了一份.yml的文档,可以看到左边是yaml格式的文档,右边是swagger-editor转换成的接口文档,还是比较清晰的,他的智能提示也是非常人性化的;要学习yaml,直接参考官网就可以了,半小时保证会。
执行如下命令启动swagger-ui;如过8081端口被占用,http-server会自动启动另一个端口
yarn run build
打开的这个页面是不是很熟悉,对,就是editor中右边的页面;在真实的环境中,我们会有自己的数据,那怎么实现从editor到ui的数据传输呢?答案就在editor,editor有导出json的功能,而swagger-ui支持yaml转换为json的文件,将其放在和swagger-ui目录下与index.hmtl同一目录下即可。
点击editor导航栏中的File,在弹出的下拉菜单中选择Download JSON,浏览器自动下载由yaml已经转换好的JSON文档
将导出的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, // ...
swagger-editor和swagger-ui的使用可以说是非常简单,对于在不动手写代码的情况下,前端和后端的沟通就会非常简单有效。对于再开发环境中的配置,这就不涉及了,工具是为了高效工作的,不是折腾的,so..到此为止。