requestBody 没有出现在调用中

Question

当我定义一个 requestBody 时，它没有出现在 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（OAS3 支持已在 Swagger UI v. 3.1 中添加）。您需要更新您的 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

requestBody 没有出现在调用中

The requestBody doesn't show up in the call

javascript

swagger

openapi