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

---

English version