Mongoose 中如何使用 OpenAPI 和 Swagger 来生成 API 文档-JavaScript中文网-JavaScript教程资源分享门户

在前后端分离的项目中，接口文档对于开发效率和代码可读性都非常重要，而生成接口文档也是一项枯燥并容易出错的工作。本文将介绍如何在 Mongoose 中使用 OpenAPI 和 Swagger 自动生成 API 文档，以提高生成接口文档的效率和准确性。

什么是 OpenAPI 和 Swagger

OpenAPI（原名 Swagger）是一个用于 RESTful API 的规范和工具集。OpenAPI 旨在定义 RESTful API 的接口描述、请求和响应参数、返回格式等详细规范，使得开发者可以更加快速和准确地开发和使用 RESTful API。

Swagger 是 OpenAPI 规范的实现和工具集，它可以根据 OpenAPI 规范自动生成 API 文档，依照请求参数和响应数据格式自动生成代码示例，支持多种编程语言和框架。

如何集成 OpenAPI 和 Swagger

在项目中安装 express-openapi-validator 和 swagger-ui-express 库，分别用于 OpenAPI 验证和 Swagger UI 展示。

npm install express-openapi-validator swagger-ui-express

在项目中创建 api.yml 文件，用于描述 RESTful API 的接口文档，具体格式可参考 OpenAPI 规范。
创建一个 swagger.js 文件，通过 swaggerUi.setup 和 swaggerUi.serve 将 Swagger UI 集成到应用中。

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./api.yml');

module.exports = (app) => {
  app.use('/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
};

在 app.js 文件中使用 express-openapi-validator 中间件，从 api.yml 中读取接口文档并自动验证请求和响应的参数格式和类型。

// javascriptcn.com 代码示例
const path = require('path');
const express = require('express');
const { OpenApiValidator } = require('express-openapi-validator');
const swaggerUi = require('./swagger');
const app = express();

// 使用 OpenAPI Validator 验证请求和响应参数的格式和类型
new OpenApiValidator({
  apiSpec: path.resolve(__dirname, './api.yml'),
}).install(app);

// 将 Swagger UI 集成到应用中
swaggerUi(app);

// your routes...

app.listen(3000, () => {
  console.log('Server is listening on port 3000');
});

如何在 Mongoose 中使用 OpenAPI 和 Swagger

以一个简单的 Mongoose 模型 User 为例，演示如何在接口文档中定义和描述一个 RESTful API。

创建 Mongoose 模型

// javascriptcn.com 代码示例
const mongoose = require('mongoose');

const userSchema = new mongoose.Schema({
  name: String,
  age: Number,
});

const User = mongoose.model('User', userSchema);

module.exports = User;

定义 RESTful API 接口文档

在 api.yml 文件中，将 RESTful API 的接口文档定义为以下格式：

// javascriptcn.com 代码示例
openapi: 3.0.0
info:
  title: Simple API
  description: Demo for OpenAPI
  version: 1.0.0
servers:
  - url: http://localhost:3000
paths:
  /users:
    get:
      summary: Get all users
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create a user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      summary: Get a user by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: User id
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    delete:
      summary: Delete a user by id
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: User id
      responses:
        204:
          description: No content
components:
  schemas:
    User:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer

该接口文档描述了一个简单的用户管理 API，包含三个接口：

GET /users: 获取所有用户的信息，返回值是用户对象数组，每个用户对象包含 name 和 age 属性。
POST /users: 创建一个用户对象，请求体是用户对象，返回值是创建成功后用户对象。
GET /users/{id}: 获取指定 id 的用户对象，请求参数是用户 id，返回值是指定 id 的用户对象。
DELETE /users/{id}: 删除指定 id 的用户对象，请求参数是用户 id，无返回值。

编写通过 OpenAPI 验证的 Mongoose API 代码

在路由中使用 validateRequest 和 validateResponse 挂载 OpenAPI 验证的中间件，同时使用 Mongoose 编写接口逻辑代码。

// javascriptcn.com 代码示例
const express = require('express');
const { validateRequest, validateResponse } = require('express-openapi-validator');
const User = require('./models/User');
const router = express.Router();

router.get('/', async (req, res) => {
  const users = await User.find();
  res.json(users);
});

router.post('/', async (req, res) => {
  const user = await User.create(req.body);
  res.status(201).json(user);
});

router.get('/:id', async (req, res) => {
  const { id } = req.params;
  const user = await User.findById(id);
  res.json(user);
});

router.delete('/:id', async (req, res) => {
  const { id } = req.params;
  await User.findByIdAndDelete(id);
  res.sendStatus(204);
});

router.use(validateRequest());
router.use(validateResponse());

module.exports = router;

如何使用 Swagger 自动生成代码示例

使用 Swagger 的 x-codeSamples 扩展字段可以自动生成多种编程语言和框架的代码示例。在 api.yml 文件中为每个接口添加 x-codeSamples 字段，下面是一个简单的 Node.js 示例：

// javascriptcn.com 代码示例
paths:
  /users:
    get:
      summary: Get all users
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
      x-codeSamples:
        - lang: nodejs
          label: Axios
          source: |
            const axios = require('axios');
            axios.get('http://localhost:3000/users')
              .then((response) => console.log(response))
              .catch((error) => console.error(error));

在 Swagger UI 中可以看到：

总结

使用 OpenAPI 和 Swagger 可以使得文档编写、代码示例生成和接口验证等流程更加自动化和规范化，减少了手写文档和代码的错误率和时间消耗，提高了开发效率和代码质量。当然，在编写接口文档时，也需要同时注意文档的详细程度和准确性。

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/651d20ab95b1f8cacd4a53e4