Download the tools used below
http://editor.swagger.io/#/ demo
One, install swagger editor
Note: You need to install the node tool before installing swagger
Tool installation
1. node
Download link: http://nodejs.cn/
You can download the version according to your needs. My computer is win7 64bit, so the downloaded file is: node-v10.13.0-x64.msi (double-click to install, nothing special, no more explanation)
Test whether the node tool is installed successfully? Open cmd terminal
C:\Users\zz>node -v
v10.13.0
C:\Users\zz>npm -v
6.4.1
You can see that node.js is installed successfully!
1.1 Install http-server
Use node.js to install the http-server module, mainly through the http-server module to enable the http service, and run swagger-editor. By command:
npm install -g http-server
Installation record:
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\http-server
C:\Users\zz\AppData\Roaming\npm\hs -> C:\Users\zz\AppData\Roaming\npm\node_modules\http-server\bin\http-server
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
Downloaded file:
swagger-codegen-master.zip
swagger-editor-master.zip
swagger-ui-master.zip
2.1 Unzip swagger-editor-master.zip
Go to the swagger editor root directory:
C:\Users\zz>cd /d D:\Tools\API_Editor_Tools\tools\swagger\swagger-editor-master\swagger-editor-master
Run: http-server -p 8000
Note: The function of -p is to specify the port, the following 8000 is our designated port, you can enter swagger-edit to enter the editing interface by visiting localhost:8000, the edit box on the left and the preview interface on the right
D:\Tools\API_Editor_Tools\tools\swagger\swagger-editor-master\swagger-editor-master>http-server -p 8000 (Note: you need to execute this command in this directory)
Starting up http-server, serving ./
Available on:
Hit CTRL-C to stop the server
Visit via a browser: http://localhost:8000/ or http://127.0.0.1:8000 to enter the editing interface of swagger edit, with the edit box on the left and the preview interface on the right
PS：
If you don’t want to run swagger-editor through http-server, you can run it through tomcat:
First copy the swagger-editor directory to the webapps in the tomcat root directory, then run tomcat and visit localhost:8080/swagger-editor.
Two, swagger-ui environment construction
1. Create a new works folder (any directory ), then enter the works directory, execute the initialization command: npm init, the following message appears, you can write it in the place you want, or you don’t need to write it
A package.json file is generated in the works directory:
2. Unzip swagger-ui-master.zip
Copy the dist directory in the screenshot above to the D:\Tools\API_Editor_Tools\works directory:
3. Install 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 [email protected] checking installable status
Install express for half a day, but haven't installed it yet ( according to the above method, the installation was successful!! ), according to the following method, specify the mirror server to obtain resources:
Solve the problem of slow npm install: (I used the following method of changing the mirror, but the installation was still not successful, and then I installed it many times without changing the mirror, and the installation was successful)
When using NPM (Node.js package management tool) to install dependencies, the speed is very slow. In order to install Express, the installation was not successful for more than two hours after executing the command. In the end, the installation could only be cancelled. The author’s 20M bandwidth should not be the reason for my network. Later, I searched the Internet for a long time to find the best solution. During installation, you can manually specify which mirror server to obtain resources from. We can use Alibaba's mirror server in China. The command is as follows:
npm install -gd express --registry=http://registry.npm.taobao.orgYou only need to use the --registry parameter to specify the mirror server address. In order to avoid the need for the --registry parameter for each installation, you can use the following command to set it permanently (personal suggestion, don't set it permanently):
npm config set registry http://registry.npm.taobao.orgAfter changing the domestic mirror, the installation speed is very fast. Successful record of installing 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 [email protected] No repository field.
added 48 packages from 36 contributors and audited 121 packages in 1.767s
found 0 vulnerabilities
D:\Tools\API_Editor_Tools\works>
After installing express, the following information is added:
4. Create index.js
Create a new index.js file in the work directory. The content of the index.js file is as follows:
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!');
});The above /root can also be replaced with other strings
5. Then start, and run to view, as the code above is 3000 port, if there is a conflict, please modify it yourself
D:\Tools\API_Editor_Tools\works> node index.js // start command
Example app listening on port 3000!
Browser input address: http://127.0.0.1:3000/root/index.html
The official online Demo has been built locally.
Transformation journey
a. Hope to replace the official API
Export files in json format through swagger editor, such as swagger.json (this is the most important product we need)
You can refer to the official documentation to write the correct Spec that conforms to the format. OpenAPI-Specification( https://github.com/OAI/OpenAPI-Specification )
Configure the json file :
1) Copy the swagger.json file exported by the swagger editor tool to the D:\Tools\API_Editor_Tools\works\dist directory:
2) Open the D:\Tools\API_Editor_Tools\works\dist\index.html file and modify it as follows:
The index.js mentioned in the screenshot above is the file D:\Tools\API_Editor_Tools\works>node index.js mentioned above
Restart node index.js, then reopen the browser, you can see the API document you wrote based on the server API.
So far, swagger-editor and swagger-ui have been deployed! !