Swagger中如何将认证邮箱从URL参数改为请求体传递？

你的核心问题是原配置把邮箱放在了URL的query参数里，而POST请求的敏感信息（比如邮箱）应该通过**请求体（requestBody）**传递。下面是修正后的完整Swagger YAML配置，完全匹配你想要的JSON数组格式：

paths:
  /auth:
    post:
      tags:
        - 认证接口
      summary: 通过邮箱地址进行认证
      # 移除原query参数配置
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    format: email # 可选，标记为邮箱格式，Swagger会自动做格式校验
                    example: jdoe@homework.com
      responses:
        '200':
          description: 认证成功

关键改动说明： #

• 删除了原parameters下的query参数配置，彻底避免邮箱出现在URL中
• 添加requestBody节点，设置required: true标记该请求体为必填项
• 指定请求体媒体类型为application/json，并定义schema为数组类型，数组元素是包含name字段的对象
• 可选添加format: email和example，让Swagger界面提供更友好的输入提示与格式校验

配置完成后，在Swagger界面测试时会出现请求体输入框，直接填入你需要的JSON格式即可：

[
   {
    "name": "jdoe@homework.com"
   }
]

此时邮箱信息会通过请求体传递，不会出现在URL里，符合安全最佳实践。

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