一, 安装 swagger editor
说明: 安装 swagger 前需要安装 node 工具
工具安装
1. node
下载地址: http://nodejs.cn/
根据自己的需要下载版本即可, 本人电脑是: win7 64bit, 所以下载后的文件是: node-v10.13.0-x64.msi (双击安装即可, 没啥特殊的, 不再说明)
测试 node 工具是否安装成功? 打开 cmd 终端
- C:\Users\zz>node -v
- v10.13.0
- C:\Users\zz>NPM -v
- 6.4.1
可以看到 node.JS 安装成功!
1.1 安装 http-server
使用 node.JS 安装 http-server 模块, 主要通过 http-server 模块来启用 http 服务, 运行 swagger-editor. 通过命令:
NPM install -g http-server
安装记录:
- C:\Users\zz>NPM install -g http-server
- C:\Users\zz\AppData\Roaming\NPM\http-server -> C:\Users\zz\AppData\Roaming\NPM\node_modules\http-server\bin\ht
- tp-server
- C:\Users\zz\AppData\Roaming\NPM\hs -> C:\Users\zz\AppData\Roaming\NPM\node_modules\http-server\bin\http-server
- + http-server@0.11.1
- added 25 packages from 28 contributors in 9.118s
- C:\Users\zz>
- 2.swagger
- https://github.com/swagger-api/swagger-codegen
- https://github.com/swagger-api/swagger-editor
- https://github.com/swagger-api/swagger-ui
- https://github.com/swagger-api
下载后的文件:
- swagger-codegen-master.zip
- swagger-editor-master.zip
- swagger-ui-master.zip
2.1 解压 swagger-editor-master.zip
进入到 swagger editor 根目录:
C:\Users\zz>cd /d D:\Tools\API_Editor_Tools\tools\swagger\swagger-editor-master\swagger-editor-master
运行: http-server -p 8000
说明:-p 的作用是指定端口, 后面的 8000 就是我们指定的端口, 访问 localhost:8000 就可以进入 swagger-edit 就可以进入编辑界面了, 左边是编辑框, 右边是预览界面
- D:\Tools\API_Editor_Tools\tools\swagger\swagger-editor-master\swagger-editor-master>http-server -p 8000 (注意: 需要到该目录下执行此命令)
- Starting up http-server, serving ./
- Available on:
- http://192.168.191.1:8000/
- http://192.168.39.187:8000/
- http://127.0.0.1:8000/
- Hit CTRL-C to stop the server
通过浏览器访问: http://localhost:8000/ 或 http://127.0.0.1:8000/ 即可进入 swagger edit 的编辑界面了, 左边是编辑框, 右边是预览界面
PS:
如果不愿用通过 http-server 来运行 swagger-editor, 可以通过 tomcat 来运行:
首先把 swagger-editor 目录复制到 tomcat 根目录的 webapps, 然后运行 tomcat, 访问 localhost:8080/swagger-editor 就可以了
二, swagger-ui 环境搭建
1. 新建 works 文件夹, 然后进入到 works 目录, 执行初始化命令: NPM init , 出现如下信息, 填的地方可以随便写, 也可以不写
works 目录下生成了一个 package.JSON 文件:
2. 解压 swagger-ui-master.zip
将上截图中的 dist 目录复制到 D:\Tools\API_Editor_Tools\works 目录下:
3. 安装 express
- D:\Tools\API_Editor_Tools\works>NPM install express
- NPM WARN registry Unexpected warning for https://registry.npmjs.org/ : Miscellaneous Warning ETIMEDOUT: request to https:
- // http://registry.npmjs.org/bytes failed, reason: connect ETIMEDOUT 104.16.19.35:443
- NPM WARN registry Using stale package data from https://registry.npmjs.org/ due to a request error during revalidation.
- [..................] \ loadDep:statuses: sill resolveWithNewModule ms@2.0.0 checking installable status
安装 express 半天, 还没有安装上, 按照如下方法, 指定镜像服务器获取资源:
解决 NPM install 慢的问题: (我使用下面换镜像的方法, 依然没有安装成功, 后来多次安装, 不换镜像, 又安装成功了)
使用 NPM(Node.JS 包管理工具) 安装依赖时速度特别慢, 为了安装 Express, 执行命令后两个多小时都没安装成功, 最后只能取消安装, 笔者 20M 带宽, 应该不是我网络的原因, 后来在网上找了好久才找到一种最佳解决办法, 在安装时可以手动指定从哪个镜像服务器获取资源, 我们可以使用阿里巴巴在国内的镜像服务器, 命令如下:
NPM install -gd express --registry=http://registry.npm.taobao.org
只需要使用 - registry 参数指定镜像服务器地址, 为了避免每次安装都需要 --registry 参数, 可以使用如下命令进行永久设置 (个人建议, 不要永久设置):
NPM config set registry http://registry.npm.taobao.org/
换了国内镜像, 安装速度就很快了.
最后安装 express 成功记录:
- C:\Users\zz>cd /d D:\Tools\API_Editor_Tools\works
- D:\Tools\API_Editor_Tools\works>NPM install express
- NPM notice created a lockfile as package-lock.JSON. You should commit this file.
- NPM WARN note_app@1.0.0 No repository field.
- + express@4.16.4
- added 48 packages from 36 contributors and audited 121 packages in 1.767s
- found 0 vulnerabilities
- D:\Tools\API_Editor_Tools\works>
安装 express 后, 多了如下信息:
4. 创建 index.JS
work 目录下 新建 index.JS 文件, index.JS 文件内容如下:
- var express = require('express');
- var App = express();
- App.use('/root', express.static('dist'));
- App.get('/', function (req, res) {
- res.send('Hello World!');
- });
- App.listen(3000, function () {
- console.log('Example app listening on port 3000!');
- });
上述 / root 也可以换成其他字串
5. 然后启动, 并运行查看, 如上代码为 3000 端口, 如有冲突请自行修改
- D:\Tools\API_Editor_Tools\works>node index.JS // 启动命令
- Example App listening on port 3000!
浏览器输入地址: http://127.0.0.1:3000/root/index.html
在线的官方的 Demo 已经在本地搭建好了.
改造之旅
a. 希望替换官方的 API
通过 swagger editor 导出 JSON 格式的文件如: swagger.JSON (这是我们需要的最重要的产物)
可以参考官方的文档, 编写正确的符合格式的 Spec.OpenAPI-Specification( https://github.com/OAI/OpenAPI-Specification )
配置 JSON 文件:
1) 将 swagger editor 工具导出的 swagger.JSON 文件拷贝到 D:\Tools\API_Editor_Tools\works\dist 目录下:
2) 打开 D:\Tools\API_Editor_Tools\works\dist\index.HTML 文件, 修改如下:
上面截图提到的 index.JS 是上面提到的 D:\Tools\API_Editor_Tools\works>node index.JS 这个文件
重启 node index.JS, 然后重新打开浏览器, 可以看到自己根据服务端 API 编写的 API 文档.
到此 swagger-editor 和 swagger-ui 已经部署完毕了!!
参考:
- https://testerhome.com/topics/8168
- https://www.jianshu.com/p/d6626e6bd72c
来源: http://www.bubuko.com/infodetail-2855698.html