swagger环境搭建

下面所用工具下载

 

http://editor.swagger.io/#/  demo

 

1、安装 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就能够了

 

2、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:

//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://blog.csdn.net/ron03129596/article/details/53559803

https://www.jianshu.com/p/d6626e6bd72c  

 

http://www.javashuo.com/article/p-teudrtjs-gp.html    功能强大的swagger-editor的介绍与使用