swagger UI本地搭建与使用

"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进行再次编译。

使用

如果只是上面的搭建的话,通常情况下不能完全满足需求。比如:

  1. 虽然Swagger提供了配套的Editor编辑工具,我们仍然需要做点工作将两者结合起来。
  2. 虽然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。

推荐阅读更多精彩内容