requestBody没有显示在通话中

Question

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

到目前为止，我已经尝试像下面的代码一样声明它。我没有尝试使用它制作一个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