Swagger UI教程 API 文档神器 搭配Node使用
在团队开发中，一个好的 API 文档可以减少很多 交流成本 ，也可以使一个新人快速上手业务。
前言
- swagger ui 是一个API在线文档生成和测试的利器，目前发现最好用的。
- 为什么好用？ Demo 传送门
- 支持API自动生成同步的在线文档
- 这些文档可用于项目内部API审核
- 方便测试人员了解API
- 这些文档可作为客户产品文档的一部分进行发布
- 支持API规范生成代码，生成的客户端和服务器端骨架代码可以加速开发和测试速度 </ul> </li> </ul> </li> </ul>
- 下载Swagger UI（也可以直接下载 zip 文件）
总结一句话就是好用，逼格高。下面我将总结一下如何快速在本地搭建一个基于Node和Swagger UI的 API 的文档工具
环境搭建
git clone https://github.com/swagger-api/swagger-ui.git
- 安装 express
- 创建一个空文件夹 node_app
mkdir node_app
- 初始化 node ，创建package.json文件（）
➜ ~ ✗ >cd node_ap ➜ ~/node_app ✗ >npm init // 下面的看你心情填写 name: (node_app) node_app version: (1.0.0) description: entry point: (index.js) test command: git repository: keywords: author: license: (ISC)
- 安装 express
➜ ~/node_app git:(master) ✗ >npm install express --save
- 创建 index.js
➜ ~/node_app git:(master) ✗ >vim index.js
- 把下面代码贴如 index.js 中
var express = require('express'); var app = express(); app.get('/', function (req, res) { res.send('Hello World!'); }); app.listen(3000, function () { console.log('Example app listening on port 3000!'); });- 在 node_app 中创建空目录 public
➜ ~/node_app git:(master) ✗ >mkdir public ➜ ~/node_app git:(master) ✗ >cd public
- 修改路由
➜ ~/node_app/public git:(master) ✗ >vim ../index.js //在文件第三行插入下面这句话 app.use('/static', express.static('public')); - 把下载好的Swagger UI 文件中dist 目录下的文件全部复制到 public 文件夹下。
目录结构 - 开启 node
➜ ~/node_app git:(master) ✗ >node index.js
- 打开浏览器，输入 http://localhost:3000/static/index.html
到此为止，你已经把官方的 demo 在本地配置好了。当然你也可以吧这个搭建在服务器上
编写文档并发布
- 使用 Swagger Editor 编写 API 文档
- Swagger Editor 上的是基于 yaml 的语法，但是不用害怕，看着官方的 demo 看个10分钟就会了。
- 导出 test.json 文档
导出方式 - 把 test.json 放到 node_app/public 目录下。
- 利用编辑器修改 url = "http://petstore.swagger.io/v2/swagger.json"; 为 url = "/static/test.json";
- 重启 node 服务，浏览器中打开 http://localhost:3000/static/index.html 就是你自己写的 api 文档了 </ul>
效果图
自己写的 API 接口
PUT请求</div>
GET请求</div>
POST 请求</div>本文由用户 TeelaFlo42 自行上传分享，仅供网友学习交流。所有权归原作者，若您的权利被侵害，请联系管理员。转载本站原创文章，请注明出处，并保留原始链接、图片水印。本站是一个以用户分享为主的开源技术平台，欢迎各类分享！
- 支持API自动生成同步的在线文档
