swagger-editor和swagger-ui的搭建

系统：Ubuntu 16.04LTS

1.swagger-editor

• 当然官方提供了在线的编辑方式，这里实现的是本地swagger-editor的使用
• swagger-editor主要是编写api接口文档，但需要配合swagger-ui来查看，里面的代码格式为yaml，但编辑后可以导出yml/json文件

• 0.前提：安装了nodejs和npm
  可参考Ubuntu软件安装

node -v
npm -v

• 1.先安装http-server(-g 表示全局安装)
  关于http-server：基于nodejs的http服务器，零配置，方便使用

npm install -g http-server

• 2.获取并解压源码

wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.4/swagger-editor.zip
unzip swagger-editor.zip

• 3.使用http-server启动

http-server swagger-editor

若想更换默认端口启动，增加参数

http-server –p 8081 swagger-editor

启动成功：

Starting up http-server, serving swagger-editor
Available on:
  http://127.0.0.1:8081
  http://192.168.0.79:8081
Hit CTRL-C to stop the server

使用浏览器访问http://192.168.0.79:8081即可

参考：
github源码
官方文档

2.swagger-ui

两种方式：A.扩展版，B.官方版

A.扩展版(使用Tomcat)

image.png

• 1.在sosoapi注册，登录后下载SwaggerUI扩展版
• 2.根据sosoapi官方的部署说明安装(其实就是部署到Tomcat)
• 3.启动Tomcat，访问：http://localhost:8080/项目名/

将编辑好的API json文档放在项目的json文件夹下(yml格式的可放在yml文件夹下，归类清晰)，在界面导航栏中访问文件即可：
http://localhost:8080/swagger/yml/123.yml 或 http://localhost:8080/swagger/json/123.json

另外，sosoapi提供了表单式的编辑API方式，与swagger-editor直接编辑yml的方式相比，更简单点。

B.官方版

• 1.下载github源码

git clone https://github.com/swagger-api/swagger-ui

• 2.进入项目，都是静态文件，浏览器中打开dist文件夹下的index.html，即可看到UI界面(走file协议)，其中的json是官方的例子：Swagger Petstore
• 3.将swagger-ui项目部署到http-server服务器中，使用http协议访问。因为之前是全局安装的http-server，所以在swagger-ui所在的文件夹打开终端，直接启动即可：

http-server –p 8082 swagger-ui

• 4.修改官方默认展示的文档json
  打开swagger-ui/dist中的index.html，修改url指向自己json/yml文件夹下的文档json/yml文件

...
const ui = SwaggerUIBundle({
  //url: "http://petstore.swagger.io/v2/swagger.json",
  url: "/json/xxx.json",
dom_id: '#swagger-ui',
...

11.png

这里使用的是http-server服务器，方便快捷。也可以搭建node服务器，参考这里

Finish!