Egg.js集成Swagger API文档实战

xiangzhihong
110 阅读5分钟

一、概述

为什么选择Swagger

Swagger（现更名为OpenAPI）是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。它具有以下优势：

  • 自动生成：从代码注释自动生成API文档，减少手动编写工作量

  • 实时同步：文档与代码保持同步，避免接口变更导致文档过时

  • 交互式文档：提供可视化界面，支持在线测试API

  • 标准化：遵循OpenAPI规范，确保API文档的一致性和可读性

准备工作

在开始集成前，请确保你的Egg.js项目已正确初始化。如果还没有创建项目，可以通过以下命令快速创建：

npm init egg --type=simple
cd egg-project
npm install

二、基本使用

安装Swagger插件

Egg.js生态中有多个Swagger相关插件，其中使用最广泛的是egg-swagger-doc。通过以下命令安装：

npm install egg-swagger-doc --save

配置插件

启用插件

编辑config/plugin.js文件，添加以下配置启用egg-swagger-doc插件：

// config/plugin.js
exports.swaggerdoc = {
  enable: true,
  package: 'egg-swagger-doc',
};

配置Swagger

创建或编辑config/config.default.js文件，添加Swagger相关配置：

// config/config.default.js
exports.swaggerdoc = {
  dirScanner: './app/controller', // 扫描的控制器目录
  apiInfo: {
    title: 'Egg.js Swagger API', // API文档标题
    description: '使用Swagger自动生成Egg.js API文档', // API文档描述
    version: '1.0.0', // API版本
  },
  schemes: ['http', 'https'], // 支持的协议
  consumes: ['application/json'], // 请求内容类型
  produces: ['application/json'], // 响应内容类型
  securityDefinitions: {
    // 配置认证方式，可选
    api_key: {
      type: 'apiKey',
      name: 'Authorization',
      in: 'header',
    },
  },
  enableSecurity: false, // 是否启用认证
  enableValidate: true, // 是否启用参数校验
  routerMap: false, // 是否自动生成路由
  enable: true, // 是否启用插件
};

添加API注释

egg-swagger-doc通过解析控制器中的JSDoc风格注释来生成API文档。以下是一个示例：

// app/controller/home.js
'use strict';
 
const Controller = require('egg').Controller;
 
/**
 * @controller HomeController
 */
class HomeController extends Controller {
  /**
   * @summary 欢迎页面
   * @description 访问系统欢迎页面
   * @router get /
   * @request query string name 可选，用户名称
   * @response 200 baseResponse 成功返回
   */
  async index() {
    const { ctx } = this;
    const { name = 'Egg' } = ctx.query;
    ctx.body = {
      message: `Hello, ${name}!`,
    };
  }
  
  /**
   * @summary 创建用户
   * @description 创建新用户并返回用户信息
   * @router post /users
   * @request body createUserRequest *body
   * @response 200 userResponse 成功返回用户信息
   * @response 400 errorResponse 请求参数错误
   */
  async createUser() {
    const { ctx } = this;
    // 处理创建用户逻辑
    ctx.body = {
      id: 1,
      name: ctx.request.body.name,
      email: ctx.request.body.email,
    };
  }
}
 
module.exports = HomeController;

常用的Swagger注释标签说明：

标签说明
@controller控制器名称，用于分组API
@summaryAPI接口的简短描述
@descriptionAPI接口的详细描述
@routerAPI路由信息，格式：方法 路径
@request请求参数，格式：位置 类型 名称 是否必须 描述
@response响应结果，格式：状态码 模型名称 描述

定义数据模型

为了使API文档更加清晰，可以定义请求和响应的数据模型。在app/model目录下创建模型定义文件。

// app/model/response.js
/**
 * @model baseResponse
 * @property {integer} code 状态码，0表示成功
 * @property {string} message 提示信息
 * @property {object} data 返回数据
 */
 
/**
 * @model userResponse
 * @extends baseResponse
 * @property {object} data 用户信息
 * @property {integer} data.id 用户ID
 * @property {string} data.name 用户名
 * @property {string} data.email 用户邮箱
 */
 
/**
 * @model errorResponse
 * @extends baseResponse
 * @property {integer} code 错误码
 * @property {string} message 错误信息
 */

访问Swagger文档

启动应用后，通过以下URL访问Swagger文档界面：

http://localhost:7001/swagger-ui.html

三、高级配置

自定义Swagger UI路径

如果需要自定义Swagger UI的访问路径，可以在配置中添加urlPrefix选项：

// config/config.default.js
exports.swaggerdoc = {
  // ...其他配置
  urlPrefix: '/api-docs', // 自定义路径前缀
};

配置后，Swagger文档将通过http://localhost:7001/api-docs/swagger-ui.html访问。

环境控制

在生产环境中，你可能不希望暴露Swagger文档。可以通过环境变量控制Swagger的启用状态：

// config/config.prod.js
exports.swaggerdoc = {
  enable: false, // 生产环境禁用Swagger
};

安全认证

为了保护API文档，可以启用Swagger的安全认证功能。修改配置文件：

// config/config.default.js
exports.swaggerdoc = {
  // ...其他配置
  enableSecurity: true,
  securityDefinitions: {
    api_key: {
      type: 'apiKey',
      name: 'Authorization',
      in: 'header',
    },
  },
};

启用认证后，访问Swagger文档需要在请求头中添加Authorization参数。

四、常见问题解决

文档不更新

如果修改了注释但Swagger文档没有更新，可能是因为Egg.js的开发模式没有监测到模型文件的变化。可以手动重启应用或修改配置：

// config/config.local.js
exports.development = {
  watchDirs: ['app/model'], // 监听模型目录变化
};

中文乱码问题

如果Swagger文档中出现中文乱码，确保你的代码文件使用UTF-8编码，并在配置中添加lang选项：

// config/config.default.js
exports.swaggerdoc = {
  // ...其他配置
  lang: 'zh-CN', // 设置语言为中文
};

接口排序

默认情况下，Swagger文档中的接口是按字母顺序排列的。如果需要自定义排序，可以在注释中添加@order标签：

/**
 * @summary 欢迎页面
 * @description 访问系统欢迎页面
 * @router get /
 * @order 1
 */
async index() {
  // ...
}

通过集成Swagger，我们可以轻松实现API文档的自动生成和管理，大大提高了开发效率和文档质量。本文介绍了Egg.js集成Swagger的完整流程，包括插件安装、配置、注释编写和高级功能。

使用Swagger的好处不仅在于自动生成文档，更重要的是它促进了API设计的规范化和标准化，为团队协作提供了更好的基础。希望本文能帮助你在Egg.js项目中更好地使用Swagger。

avatar
文章
阅读
粉丝