"Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment."
Swagger是一款基于OpenAPI规范的API开发工具框架，从设计、文档、测试和部署支持整个API开发的生命周期。
其中Swagger Ui 能够动态的生成漂亮的API文档。
这里来讲一下Swagger Ui的搭建与基本使用方法。
本地搭建
准备：
- Node 6.x
- NPM 3.x
以上。这是官网提供的参数，我本地使用的node是7.10.0。
下载：
- 访问github下载整个包。
- 或使用git工具下载
git clone https://github.com/swagger-api/swagger-ui.git
dev环境
npm run dev
打开http://localhost:3200就可以看到页面了。
image.png
生产环境
下载的包中的dist文件夹为swagger预生成的包，可以直接使用。
若是需要自定义开发，可以修改后使用npm run build进行再次编译。
使用
如果只是上面的搭建的话，通常情况下不能完全满足需求。比如：
- 虽然Swagger提供了配套的Editor编辑工具，我们仍然需要做点工作将两者结合起来。
- 虽然Swagger Editor的语法简单，但是对于初上手的开发者而言仍然有一定的上手成本，在团队中推广存在一定困难。
为此，我们需要做点别的工作。
搭建配套设施
（1）新建项目
新建一个express项目，接入Swagger UI.
yarn add express --dev
把上面的dist文件复制到项目文件下。
<pre>
-express
-index.js
-package.json
-src
-index.html
-swagger-ui.js
-... // 一整个复制过来
</pre>
然后开启express服务就可以将swagger UI跑起来了。
（2）新建API文档
在swagger Ui会分析Url中的参数来进行动态生成文档，如：http://localhost:3200/?url=http://localhost:3200/static/eg.json那么变会根据eg.json来生成API文档。
用express的static为项目中的json提供静态地址。
<pre>
const app = express();
app.use('/static', express.static('./json'));
</pre>
然后新增路由，添加上传接口。将用Swagger Editor生成的json上传到服务器中。
（3）可视化图形界面
上面第二条中，使用者仍然需要自己编写yaml，然后上传Json。使用体验不佳。所以可以自己写一个图形界面的API文档输入界面，然后生成json。
网友评论