如何在 swagger 注释中定义请求对象

在使用 Swagger 进行 API 开发时，我们需要注释我们的代码以供 Swagger 自动生成 API 文档。然而，Swagger 注释并不仅仅是简单的文本，我们还可以使用它来定义请求对象的参数。

步骤

1. 在 API 方法上方加上注释标签

/**
* @swagger
* /api/endpoint:
*   post:
*     summary: API方法简介
*     description: API方法详细描述
*     tags:
*       - Endpoint
*     requestBody:
*       description: '请求参数'
*       content:
*         application/json:
*           schema:
*             type: object
*             properties:
*               key1:
*                 type: string
*               key2:
*                 type: integer
*               key3:
*                 type: array
*                 items:
*                   type: string
*```

2. 在 requestBody 对象中添加请求参数的描述

例如，我们可以使用 `description` 属性来描述请求参数，使用 `schema` 属性来定义请求参数的结构。

```markdown
/**
* @swagger
* /api/endpoint:
*   post:
*     summary: API方法简介
*     description: API方法详细描述
*     tags:
*       - Endpoint
*     requestBody:
*       description: '请求参数'
*       content:
*         application/json:
*           schema:
*             type: object
*             properties:
*               key1:
*                 type: string
*               key2:
*                 type: integer
*               key3:
*                 type: array
*                 items:
*                   type: string
*```

在上面的示例中，我们使用了 `string` 和 `integer` 来定义请求参数的数据类型，并使用 `items` 来定义数组中元素的数据类型。

## 总结

通过在 Swagger 注释中定义请求对象参数，我们可以为我们的 API 方法提供更加详细和准确的文档，让开发人员更加容易理解和调用我们的 API 接口。