一文探讨Node.js项目中怎么使用Koa2集成Swagger-js教程-PHP中文网

一文探讨Node.js项目中怎么使用Koa2集成Swagger

青灯夜游

发布： 2023-04-01 07:30:03

转载

1389人浏览过

在本文中，我们将探讨如何在node.js项目中使用koa2集成swagger，以自动生成api文档。我们将介绍swagger的基本概念、相关的npm包，并通过详细的代码示例和解释来演示整个过程。

一文探讨Node.js项目中怎么使用Koa2集成Swagger

什么是Swagger

Swagger是一款RESTful API的文档生成工具，它可以帮助开发者快速、准确地编写、维护和查阅API文档。Swagger具有以下优点：

自动生成API文档，减少手动编写的工作量
提供可视化的API接口测试工具，方便调试和验证
支持多种语言和框架，具有良好的通用性和可扩展性

创建Koa2项目

首先，我们需要创建一个基于Koa2的Node.js项目。你可以使用以下命令创建项目：【相关教程推荐：nodejs视频教程、编程教学】

mkdir koa2-swagger-demo
cd koa2-swagger-demo
npm init -y

登录后复制

然后，安装Koa2和相关依赖：

npm install koa koa-router --save

登录后复制

安装Swagger相关依赖

接下来，我们需要安装Swagger相关的NPM包。在本教程中，我们将使用koa2-swagger-ui和swagger-jsdoc。分别用于展示Swagger UI和生成API文档。

npm install koa2-swagger-ui swagger-jsdoc --save

登录后复制

配置Swagger

在项目根目录下，创建一个名为swagger.js的文件，用于配置Swagger。配置代码如下：

const swaggerJSDoc = require(&#39;swagger-jsdoc&#39;);
const options = {
    definition: {
        openapi: &#39;3.0.0&#39;,
        info: {
            title: &#39;我是标题&#39;,
            version: &#39;1.0.0&#39;,
            description: &#39;我是描述&#39;,
        },
        //servers的每一项，可以理解为一个服务,实际项目中，可自由修改
        servers: [
            {
                url: &#39;/api&#39;,
                description: &#39;API server&#39;,
            },
        ],
    },
    apis: [&#39;./routes/*.js&#39;],
};

const swaggerSpec = swaggerJSDoc(options);

// 如果有Swagger规范文件转TS的需求，可在此处保留Swagger规范文件到本地，方便使用
//fs.writeFileSync(&#39;swagger.json&#39;, JSON.stringify(swaggerSpec, null, 2));

module.exports = swaggerSpec;

登录后复制

这里，我们定义了一个名为options的对象，包含了Swagger的基本信息和API接口的来源（即我们的路由文件）。然后，我们使用swagger-jsdoc生成API文档，并将其导出。

编写API接口

现在，我们来创建一个名为routes的文件夹，并在其中创建一个名为users.js的文件，用于定义用户相关的API接口。在users.js文件中，我们将编写以下代码：

const Router = require(&#39;koa-router&#39;);
const router = new Router();

/**
* @swagger
* tags:
*   name: Users
*   description: User management
*/

/**
* @swagger
* components:
*   schemas:
*     User:
*       type: object
*       properties:
*         id:
*           type: integer
*           description: The user ID.
*         name:
*           type: string
*           description: The user&#39;s name.
*         email:
*           type: string
*           description: The user&#39;s email.
*       required:
*         - id
*         - name
*         - email
*/

/**
* @swagger
* /users:
*   get:
*     summary: Retrieve a list of users
*     tags: [Users]
*     responses:
*       200:
*         description: A list of users.
*         content:
*           application/json:
*             schema:
*               type: array
*               items:
*                 $ref: &#39;#/components/schemas/User&#39;
*/
router.get(&#39;/users&#39;, async (ctx) => {
    const users = [
        { id: 1, name: &#39;John Doe&#39;, email: &#39;john.doe@example.com&#39; },
        { id: 2, name: &#39;Jane Doe&#39;, email: &#39;jane.doe@example.com&#39; },
    ];
    ctx.body = users;
});

module.exports = router;

登录后复制

注释简析：

tags：这部分定义了一个名为"Users"的标签。标签用于对API接口进行分类和分组。在这里，标签名为"Users"，描述为"users.js下的接口"。
```
/**
 * @swagger
 * tags:
 *   name: Users
 *   description: users.js下的接口
 */
```
登录后复制
components和schemas：这部分定义了一个名为"User"的数据模型。数据模型描述了API接口中使用的数据结构。在这个例子中，"User"模型包含三个属性：id（整数类型，表示用户ID）、name（字符串类型，表示用户名）和email（字符串类型，表示用户电子邮件）。同时，id、name和email属性都被标记为必需。
```
/**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       properties:
 *         id:
 *           type: integer
 *           description: id.
 *         name:
 *           type: string
 *           description: name.
 *         email:
 *           type: string
 *           description: email.
 *       required:
 *         - id
 *         - name
 *         - email
 */
```
登录后复制
/users API接口：这部分定义了一个获取用户列表的API接口。它描述了一个GET请求，路径为/users。这个接口使用了之前定义的"Users"标签。另外，它还定义了一个成功的响应，状态码为200，表示返回一个用户列表。响应的内容类型为application/json，其结构是一个包含"User"模型的数组。
$ref: '#/components/schemas/User' 是一个引用语法，引用了之前定义在components下的schemas中名为User的数据模型。
```
/**
* @swagger
* /users:
*   get:
*     summary: 获取用户列表
*     tags: [Users]
*     responses:
*       200:
*         description: success.
*         content:
*           application/json:
*             schema:
*               type: array
*               items:
*                 $ref: &#39;#/components/schemas/User&#39;
*/
```
登录后复制

这段代码为API文档提供了有关用户管理接口、数据模型和响应格式的详细信息。Swagger JSDoc解析这些注释，并生成对应的OpenAPI文档。

生成API文档

接下来，我们需要在项目中启用Swagger UI。在项目根目录下，创建一个名为app.js的文件，然后编写以下代码：

const Koa = require(&#39;koa&#39;);
const Router = require(&#39;koa-router&#39;);
const swaggerUI = require(&#39;koa2-swagger-ui&#39;).koaSwagger;
const swaggerSpec = require(&#39;./swagger&#39;);
const usersRoutes = require(&#39;./routes/users&#39;);

const app = new Koa();
const router = new Router();

router.use(&#39;/api&#39;, usersRoutes.routes(), usersRoutes.allowedMethods());

router.get(
    &#39;/swagger&#39;,
    swaggerUI({
        routePrefix: false,
        swaggerOptions: {
            spec: swaggerSpec,
        },
    })
);

app.use(router.routes()).use(router.allowedMethods());

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server is running at http://localhost:${PORT}`);
});

登录后复制

在这里，我们导入了koa2-swagger-ui和swagger-jsdoc生成的API文档。然后，我们定义了一个名为/swagger的路由，用于展示Swagger UI。最后，我们将用户相关的API接口挂载到/api路径下。