Swagger 使用指南
Swagger（目前用OpenAPI Specification代替）是一个用于设计、构建、记录和使用REST API的强大工具。通过使用Swagger，开发者可以定义API的结构，确保API的稳定性，并生成协作所需的文档。本文将探讨使用Swagger的一些关键技巧，包括如何定义API、如何生成和展示文档等。
安装和配置Swagger
在Node.js项目中，可以利用swagger-ui-express和swagger-jsdoc等工具来集成Swagger。这些工具能够帮助记录API和生成一个交互式的用户界面，用于测试API。
首先安装依赖：
npm install swagger-jsdoc swagger-ui-express --save
初始化Swagger JSDoc
在项目中初始化Swagger JSDoc以自动生成API文档。这通常在应用程序的入口文件（比如app.js或server.js）进行配置。
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const swaggerDefinition = {
openapi: '3.0.0', // 使用OpenAPI Specification 3.0版本
info: {
title: '我的API文档',
version: '1.0.0',
description: '这是我的API文档的描述',
},
servers: [
{
url: 'http://localhost:3000',
description: '开发服务器',
},
],
};
const options = {
swaggerDefinition,
apis: ['./routes/*.js'], // 指向API文档的路径
};
const swaggerSpec = swaggerJSDoc(options);
// 使用swaggerUi提供可视化界面
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
确保把apis的路径设置成包含有注释的API文件所在的路径。
使用JSDoc注释编写文档
为了让swagger-jsdoc能够生成Swagger文件，需要在路由文件或控制器文件中添加JSDoc注释。
/**
* @swagger
* /users:
* get:
* tags: [Users]
* summary: 获取用户列表
* description: "返回当前所有用户的列表"
* responses:
* 200:
* description: 请求成功
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/User'
*/
上面的注释定义了GET /users路由，并指定了其行为和预期的响应。
定义模型
为了更好地复用和管理代码，可以在Swagger文档中定义模型（或称为schema）。
/**
* @swagger
* components:
* schemas:
* User:
* type: object
* required:
* - username
* - email
* properties:
* id:
* type: string
* description: 用户唯一标识
* username:
* type: string
* description: 用户名
* email:
* type: string
* format: email
* description: 用户邮箱地址
*/
这个模型定义了一个User对象，它有id、username和email属性。
Swagger UI的使用
启动Node.js应用后，通过访问http://localhost:3000/api-docs来查看Swagger UI。Swagger UI为你的API提供了一个交互式的用户界面，使得调用者可以无需编写代码就能测试API的各个端点。
维护和更新Swagger文档
遵循良好的文档编写实践，确保每次API更新时，都同步更新相应的Swagger注释。这有助于保持文档的准确性和有效性。
小结
通过使用Swagger，开发者可以有效地设计和文档化REST API，提高API的可读性和可维护性，同时为其他开发者、前端团队和API消费者提供一个清晰和准确的API参考。掌握上述技巧可以更好地利用Swagger来优化后端API服务器的开发流程。
实例1：express & swagger
从创建一个新的Express应用程序开始：
npm init -y
npm install express --save
编写Express服务器并加入Swagger文档。
步骤1：创建Express服务器
index.js:
const express = require('express');
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
// 初始化express应用
const app = express();
const port = 3000;
// 定义swagger文档配置
const swaggerOptions = {
swaggerDefinition: {
openapi: '3.0.0',
info: {
title: '示例API',
version: '1.0.0',
description: '这是一个简单的Express API应用示例',
},
servers: [
{
url: 'http://localhost:3000',
description: '本地开发服务器',
},
],
},
apis: ['./routes/*.js'], // 使用Glob模式指定API文件位置
};
// 初始化swagger-jsdoc
const swaggerDocs = swaggerJSDoc(swaggerOptions);
// 提供Swagger的UI界面
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
// 定义一个简单的路由处理函数
app.get('/', (req, res) => {
res.send('欢迎使用示例API');
});
// 监听指定的端口
app.listen(port, () => {
console.log(`服务器正在监听 http://localhost:${port}`);
});
步骤2：创建路由并添加Swagger注释
假设有一个用户相关的API，为此创建一个处理用户请求的路由文件。
routes/users.js:
/**
* @swagger
* /users:
* get:
* tags:
* - 用户
* summary: 获取用户列表
* description: 请求所有注册用户信息
* responses:
* 200:
* description: 请求成功返回用户列表
* content:
* application/json:
* schema:
* type: array
* items:
* $ref: '#/components/schemas/User'
*
* components:
* schemas:
* User:
* type: object
* properties:
* id:
* type: integer
* format: int64
* description: 用户的唯一标识符
* name:
* type: string
* description: 用户的姓名
* email:
* type: string
* format: email
* description: 用户的邮件地址
*/
const express = require('express');
const router = express.Router();
// GET请求 - 获取用户列表
router.get('/', (req, res) => {
// 模拟一些用户数据
const users = [
{ id: 1, name: '张三', email: 'zhangsan@example.com' },
{ id: 2, name: '李四', email: 'lisi@example.com' },
];
res.json(users);
});
module.exports = router;
将此路由文件添加到Express应用中：
修改index.js并在顶部添加以下内容：
const userRoutes = require('./routes/users');
然后，在index.js中的Swagger UI代码下面，添加以下代码，以将用户路由挂载到Express应用：
app.use('/users', userRoutes);
运行Express服务器并访问http://localhost:3000/api-docs时，将看到带有用户路由的Swagger UI界面，这个界面提供了一个交互式的API文档。
如此一来就为Express API路由创建了Swagger文档。通过添加更多路由和适当的Swagger注释，可以继续为其他API端点拓展文档。
示例2：koa & swagger
如果使用的是Koa.js框架而非Express.js，依然可以使用Swagger来生成API文档，但是整合方式会有所不同，因为Koa的中间件机制和Express略有差异。这里以koa和koa-router为例来实现增加Swagger文档的步骤。
步骤1：创建Koa服务器
首先，安装Koa相关的依赖：
npm init -y
npm install koa koa-router --save
接下来，安装Swagger相关的依赖：
npm install koa-swagger-decorator --save
然后，创建Koa服务器和路由：
index.js:
const Koa = require('koa');
const Router = require('koa-router');
const { swagger, swaggerRouter } = require('./swagger');
const app = new Koa();
const router = new Router();
// 在路由中定义一个简单的GET请求处理
router.get('/', async (ctx) => {
ctx.body = '欢迎使用示例API';
});
// 将Swagger路由装载到Koa应用
swaggerRouter(app);
// 装载所有路由子项
app.use(router.routes()).use(router.allowedMethods());
const port = 3000;
app.listen(port, () => {
console.log(`服务器运行在 http://localhost:${port}`);
});
步骤2：配置Swagger文档并为路由添加注解
创建Swagger配置文件：
swagger.js:
const { SwaggerRouter } = require('koa-swagger-decorator');
const swaggerRouter = new SwaggerRouter();
// Swagger配置信息
swaggerRouter.swagger({
title: 'Koa 示例API',
description: 'API文档',
version: '1.0.0',
// swagger文档页面的访问路径
swaggerHtmlEndpoint: '/swagger-html',
// swagger文档的json访问路径
swaggerJsonEndpoint: '/swagger-json',
// API服务器信息
swaggerOptions: {
host: 'localhost:3000',
},
});
// 在这里可以批量加入路由定义或一个个添加
// swaggerRouter.mapDir(__dirname);
module.exports = {
swagger: swaggerRouter.swagger.bind(swaggerRouter),
swaggerRouter: swaggerRouter.routes.bind(swaggerRouter),
};
添加路由和Swagger注解：
users.js:
const { request, summary, query, tags } = require('koa-swagger-decorator');
const router = require('koa-router')();
// 定义tag
const tag = tags(['用户']);
// 用户路由的Swagger注解
router.get('/users', tag, summary('获取用户列表'), query({
name: { type: 'string', required: false, description: '按姓名查询' }
}), async (ctx) => {
// 这里可以根据name来获取用户信息
// 为了示例使用静态数据
const users = [
{ id: 1, name: '张三' },
{ id: 2, name: '李四' },
];
ctx.body = { code: 0, data: users };
});
module.exports = router;
将此路由注解文件添加到Koa应用中，方法是在index.js中添加下面的代码：
const userApi = require('./users');
swaggerRouter.use(userApi.routes());
注意：确保在代码中按自己实际的文件结构引入合适的路径。
以上代码将一个简单的Koa应用转换为使用koa-swagger-decorator来生成swagger文档。启动该应用程序后，访问http://localhost:3000/swagger-html即可看到Swagger UI。
示例3：Egg & swagger
如果使用的是Egg.js框架，并希望集成Swagger来生成API文档，则需要使用一些与Egg.js兼容的插件。Egg.js是基于Koa.js的更高层的框架，它有自己的插件系统。下面的举例将展示如何使用egg-swagger-doc这个Egg.js插件为API生成Swagger文档。
步骤1：安装egg-swagger-doc插件
首先，在Egg.js项目中安装egg-swagger-doc插件：
npm install egg-swagger-doc --save
步骤2：启用插件
在Egg.js的配置文件中启用Swagger文档插件。通常会在config/plugin.js中启用：
// config/plugin.js
exports.swaggerdoc = {
enable: true, // 启用swagger-ui插件
package: 'egg-swagger-doc',
};
步骤3：配置Swagger插件
配置Swagger插件通常在config/config.default.js中进行：
// config/config.default.js
module.exports = (appInfo) => {
const config = {};
// ... 其他配置 ...
// 配置egg-swagger-doc
config.swaggerdoc = {
dirScanner: './app/controller', // 配置自动扫描的控制器路径
apiInfo: {
title: 'Egg.js API', // API文档的标题
description: 'Swagger API for Egg.js', // API文档描述
version: '1.0.0', // 版本号
},
schemes: ['http', 'https'], // 配置支持的协议
consumes: ['application/json'], // 指定处理请求的提交内容类型 (Content-Type)，如 application/json, text/html
produces: ['application/json'], // 指定返回的内容类型
securityDefinitions: { // 配置API安全授权方式
// e.g. apikey (下面是一些例子，需要自行定制)
// apikey: {
// type: 'apiKey',
// name: 'clientkey',
// in: 'header',
// },
// oauth2: {
// type: 'oauth2',
// tokenUrl: 'http://petstore.swagger.io/oauth/dialog',
// flow: 'password',
// scopes: {
// 'write:access_token': 'write access_token',
// 'read:access_token': 'read access_token',
// },
// },
},
enableSecurity: false,
// enableValidate: true, // 是否启用参数校验插件，默认为true
routerMap: false, // 是否启用自动生成路由，默认为true
enable: true, // 默认启动swagger-ui
};
return config;
};
步骤4：使用JSDoc注释编写控制器代码
在Egg.js控制器文件app/controller/home.js中，用JSDoc注释定义API：
'use strict';
const Controller = require('egg').Controller;
/**
* @controller Home API接口
*/
class HomeController extends Controller {
/**
* @summary 首页
* @description 获取首页信息
* @router get / 这里对应路由
* @request query string name 名字
* @response 200 baseResponse 返回结果
*/
async index() {
const { ctx } = this;
ctx.body = `hello, ${ctx.query.name}`;
}
}
module.exports = HomeController;
这里利用了egg-swagger-doc所支持的JSDoc注解，定义了一个对应GET /的API。
步骤5：启动Egg.js应用并访问Swagger文档
启动Egg.js应用：
npm run dev
在浏览器中访问http://localhost:7001/swagger-ui.html（默认Egg.js应用的端口是7001）查看Swagger文档。
这就完成了在基于Egg.js框架的项目中集成Swagger文档的步骤。以上是一个简单的例子，实际开发中可能需要根据自己的业务需求进行相应的配置和编写。通过集成Swagger，所开发的Egg.js应用将获得一个自动化、易于阅读和管理的API文档。