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的介紹與使用