如何在Swagger中通过POST请求发送raw body并解决后端接收为空问题

问题根源 #

你当前的Swagger注解配置存在参数位置声明错误，是导致请求体无法正常发送的核心原因：你使用了非法的in: data参数位置值，Swagger无法识别该配置，因此不会将你填写的JSON内容作为请求体发送给后端。

可行解决方法 #

根据你项目使用的Swagger/OpenAPI版本选择对应方案即可：

方案1：适配Swagger 2.0（OpenAPI 2.0） #

直接修改parameters段的配置，将in: data改为in: body即可，修正后的注解如下：

/**
 * @swagger
 * /api/v1/index/nocache?method=checkIfPaymentIsValidForDays:
 *    post:
 *     summary: Frontend API
 *     description: Check If Custom Payment Link Is Valid For Given Days
 *     consumes: 
 *       - application/json
 *     parameters:
 *       - in: body
 *         name: data
 *         description: The data will contain order_id and valid_for
 *         required: true # 建议加上必填声明，避免空请求
 *         schema:      # Request body contents
 *           type: object
 *           properties:
 *              order_id: 
 *                type: string
 *              valid_for:
 *                type: integer
 *           required: # 建议声明必填字段
 *             - order_id
 *             - valid_for
 *     responses:
 *       '200':
 *          description: Response success or failure
 *          content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 code:
 *                   type: integer
 *                 status:
 *                   type: string
 *                 msg:
 *                   type: string
 *                 data:
 *                   type: object
 *               example:
 *                  code: 200
 *                  status: success
 *                  msg: success
 *                  data: {"isValid": true}
 */

方案2：适配OpenAPI 3.0及以上版本 #

如果你的项目使用的是OpenAPI 3.0+规范，请求体不能写在parameters段中，需要使用专门的requestBody字段声明，修正后的配置如下：

/**
 * @swagger
 * /api/v1/index/nocache?method=checkIfPaymentIsValidForDays:
 *    post:
 *     summary: Frontend API
 *     description: Check If Custom Payment Link Is Valid For Given Days
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *                order_id: 
 *                  type: string
 *                valid_for:
 *                  type: integer
 *             required:
 *               - order_id
 *               - valid_for
 *     responses:
 *       '200':
 *          description: Response success or failure
 *          content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 code:
 *                   type: integer
 *                 status:
 *                   type: string
 *                 msg:
 *                   type: string
 *                 data:
 *                   type: object
 *               example:
 *                  code: 200
 *                  status: success
 *                  msg: success
 *                  data: {"isValid": true}
 */

验证步骤 #

• 修改配置后重启服务，重新生成Swagger接口文档
• 打开Swagger UI对应接口页，确认出现Request body输入区域
• 填写符合格式的JSON后发起请求，即可在后端拿到非空的_rawBody数据

内容的提问来源于stack exchange，提问作者Aditya Vyas