javascript - requestBody 未出现在通话中

Question

当我定义 requestBody 时，它不会显示在 swagger 文档中。我想为 swagger 中的 gpx 文件创建一组图像和单个文件上传。如何才能实现 requestBody 像参数属性一样显示？

到目前为止，我已经尝试像下面的代码一样声明它。我没有尝试从中创建 requestBodies 组件并调用该引用，但我认为这不是问题所在。

/**
 * @openapi
 * /routes:
 *   post:
 *     description: Create a route
 *     tags:
 *       - Routes
 *     security:
 *       - CustomToken: []
 *     requestBody:
 *       content:
 *         multipart/form-data:
 *           schema:
 *             type: object
 *             required:
 *               - images
 *               - track
 *             properties:
 *               images:
 *                 type: array
 *                 minItems: 1
 *                 maxItems: 3
 *                 items:
 *                   type: string
 *                   format: binary
 *               track:
 *                 type: string
 *                 format: binary
 *             encoding:
 *               images:
 *                 contentType: image/png, image/jpeg
 *     parameters:          
 *       - name: name
 *         description: Name of the route.
 *         in: query
 *         required: true
 *         type: string
 *         example: Utrecht naar Den Bosch
 *       - name: description
 *         description: Description of the route.
 *         in: query
 *         required: true
 *         type: string
 *         example: Een route die langs de prachtigste punten gaat op de route van utrecht naar Den Bosch.
 *       - name: price
 *         description: The price of the route using the purchasable coins as the currency.
 *         in: query
 *         required: true
 *         type: integer
 *         minimum: 0
 *         example: 1
 *       - name: rating
 *         description: The rating the route has been given.
 *         in: query
 *         required: false
 *         type: integer
 *         minimum: 1
 *         maximum: 5
 *         example: 5
 *       - name: tags
 *         description: The tags that define if the route contains dikes, forests, mountains or cities. To select multiple values hold ctrl and click on the values you want.
 *         in: query
 *         required: true
 *         type: array
 *         minItems: 1
 *         maxItems: 4
 *         uniqueItems: true
 *         items:
 *           type: string
 *           enum:
 *             - Dike
 *             - Forest
 *             - Mountain
 *             - City
 *         example:
 *           - Dike
 *           - Forest
 *     responses:
 *       200:
 *         description: succesfully created a route
 */

根据我找到的示例，这就是声明 requestBody 的方式。但这些值不会显示在 swagger 文档文件中，如下所示:

Answer 1

3.0.12 是 Swagger UI 的一个非常旧的版本，不支持 OpenAPI 3.0(在 Swagger UI v. 3.1 中添加了 OAS3 支持)。您需要更新 Swagger UI。最新版本(撰写本文时为 3.22)正确显示 OpenAPI 3.0 请求正文。

注释还存在一些问题:

• 在请求正文中，encoding 必须与 schema 处于同一级别，并且不能位于 schema 内。

• 参数类型定义必须包装到schema中，如下所示:

  *       - name: price
  *         description: The price of the route using the purchasable coins as the currency.
  *         in: query
  *         required: true
  *         schema:          # <------
  *           type: integer
  *           minimum: 0
  *         example: 1
  
  ...
  
  *       - name: tags
  *         description: The tags that define if the route contains dikes, forests, mountains or cities. To select multiple values hold ctrl and click on the values you want.
  *         in: query
  *         required: true
  *         schema:          # <------
  *           type: array
  *           minItems: 1
  *           maxItems: 4
  *           uniqueItems: true
  *           items:
  *             type: string
  *             enum:
  *               - Dike
  *               - Forest
  *               - Mountain
  *               - City
  *         example:
  *           - Dike
  *           - Forest