Swagger UI教程 API 文档神器 搭配Node使用
ASP.NET Web API 使用Swagger生成在线帮助测试文档
前言
- swagger ui是一个API在线文档生成和测试的利器,目前发现最好用的。
- 为什么好用?Demo 传送门
- 支持API自动生成同步的在线文档
- 这些文档可用于项目内部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'));

目录结构
➜ ~/node_app git:(master) ✗ >node index.js
到此为止,你已经把官方的 demo 在本地配置好了。当然你也可以吧这个搭建在服务器上
编写文档并发布
- Swagger Editor 上的是基于 yaml 的语法,但是不用害怕,看着官方的 demo 看个10分钟就会了。

导出方式
url = "http://petstore.swagger.io/v2/swagger.json";
为url = "/static/test.json";
http://localhost:3000/static/index.html
就是你自己写的 api 文档了效果图

自己写的 API 接口

PUT请求

GET请求

POST 请求

DELETE 请求
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步