Swagger UI教程 API 文档神器搭配Node使用

ASP.NET Web API 使用Swagger生成在线帮助测试文档

Swagger 生成 ASP.NET Web API

前言

swagger ui是一个API在线文档生成和测试的利器，目前发现最好用的。
为什么好用？Demo 传送门
支持API自动生成同步的在线文档

这些文档可用于项目内部API审核
方便测试人员了解API
这些文档可作为客户产品文档的一部分进行发布
支持API规范生成代码，生成的客户端和服务器端骨架代码可以加速开发和测试速度

总结一句话就是好用，逼格高。下面我将总结一下如何快速在本地搭建一个基于Node和Swagger UI的 API 的文档工具

环境搭建

下载Swagger UI（也可以直接下载 zip 文件）

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 文档了

效果图

自己写的 API 接口

PUT请求

GET请求

POST 请求

DELETE 请求