
> 标签：`#OpenAPI` `#requestBody` `#content` `#媒体类型` `#文件上传`

---

## 实践问题

很多公司的后台，技术架构上采用 SaaS 模式：同一套接口要同时服务 Web 页面、移动端、第三方集成。

某接口在 Web 页面里用 JSON 提交，在文件导入场景里却要用 `multipart/form-data` 提交。

Swagger 2.0 里 `in: body` 只能有一个，而且没法表达 `application/x-www-form-urlencoded`；文件上传靠 `in: formData` + `type: file`，与 JSON 请求体泾渭分明。

结果对接方只能靠口头约定：「这种情况你发表单，那种情况你发 JSON」。联调时反复踩坑：前端发了表单，后端按 JSON 解析；或者后端期望文件，前端却传了 base64 字符串。

---

## API思想进化

**媒体类型成为一等公民，前后端的内容协商从口头约定变成机读契约。**

HTTP 请求体天然可以对应多种媒体类型。规范应该让每种媒体类型各自映射到自己的 schema，而不是把「接口能收什么格式」藏在文档注释或团队记忆里。

---

## 旧写法 vs 新写法

![02-request-body-comparison.png](https://developer.qcloudimg.com/http-save/yehe-11563618/ff9bfc44d8d2dd3ef2ae71c576268525.png)

*图：2.0 body/formData 分家 vs 3.0+ requestBody.content 菜单*

### 2.0：body 与 formData 两条支路

Swagger 2.0 把请求体拆成两条互不相交的路线。问题：
- 一个操作只能有一个 `in: body` 参数；
- `consumes` 是全局或操作级，不能与多种 schema 精细映射；
- `in: formData` 与 `in: body` 不能共存，无法表达「同一接口既收 JSON 又收表单」。


```yaml
swagger: '2.0'
paths:
  /users:
    post:
      consumes:
        - application/json
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/CreateUser'
  /upload:
    post:
      consumes:
        - multipart/form-data
      parameters:
        - name: file
          in: formData
          required: true
          type: file
```


### 3.0+：`requestBody.content` 媒体类型菜单

OpenAPI 3.0 用 `requestBody.content` 把媒体类型变成一等公民。

同一接口下，三种媒体类型各走各的 schema，内容协商一目了然。

文件上传统一用 `format: binary`，不再写 `type: file`。

```yaml
openapi: '3.0.3'
paths:
  /users:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateUser'
          multipart/form-data:
            schema:
              type: object
              properties:
                avatar:
                  type: string
                  format: binary
      responses:
        '201':
          description: 创建成功
```



### 案例：Swagger Petstore - OpenAPI 3.0

这个案例展示了同一操作同时支持 `application/json` 和 `application/xml`。

```yaml
openapi: 3.0.4
# ...
paths:
  /pet:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '200':
          description: Successful operation
```

来源：`https://app.swaggerhub.com/apis/smartbear/0-0-0/1.0.0` 。


### 案例：Azure AI Foundry Models Service（3.2.0）

Azure AI Foundry 的 `requestBody.content` 更复杂，同时包含 `application/json` 和 `multipart/form-data`：

```yaml
openapi: 3.2.0
# ...
paths:
  /files:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                purpose:
                  type: string
          application/json:
            schema:
              type: object
              # ...
```

来源：`https://app.swaggerhub.com/apis/westriverconsulting/azure-ai-foundry-models-service/v1`

---

## 真实案例佐证（优先 SwaggerHub）

- **Swagger Petstore - OpenAPI 3.0**：`https://app.swaggerhub.com/apis/smartbear/0-0-0/1.0.0`
  - 同一操作支持 JSON 和 XML。
- **Azure AI Foundry Models Service（3.2.0）**：`https://app.swaggerhub.com/apis/westriverconsulting/azure-ai-foundry-models-service/v1`
  - 同一接口同时支持 JSON 和 multipart/form-data，适合文件+元数据混合提交。
- **Modern Petstore API（3.2.0）**：`https://app.swaggerhub.com/apis/hcm-a45/S3V2/1.0.0`
  - 现代化 3.2 示例，含多种 content 类型。

---

## 落地 checklist

1. **同一接口多种媒体类型**：用 `requestBody.content` 分别定义 schema，不要用 `consumes` 一带而过。
2. **`required: true` 放在 `requestBody` 上**，而不是某个 media type 上。
3. **JSON 与表单可以复用同一 schema**，用 `$ref` 减少双份定义。
4. **文件上传统一用 `type: string` + `format: binary`**，别再写 Swagger 2.0 的 `type: file`。
5. **内容协商要落到契约**：不要在 wiki 或注释里写「这种情况发表单」，要让机器能读。
6. **老项目迁移**：把 `in: body` → `requestBody.content.application/json`，把 `in: formData` + `type: file` → `multipart/form-data` + `format: binary`。

---

## 下一篇预告

文章 03 · 公共错误体该放哪儿？用 components 把文档越写越短

标签：#OpenAPI #requestBody #content #媒体类型 #文件上传

02-同一接口既收 JSON 又收表单，Swagger 怎么写？

聊聊开放 API 的 Swagger 描述规范

后端

开发工具

架构设计

"OpenAPI 3.0+通过requestBody.content支持多格式请求，解决Swagger2.0中JSON与表单无法共存的问题。文件上传统一使用format:binary，实现内容协商契约化，提升API开发效率。"

代码解释

SaaS

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

02-同一接口既收 JSON 又收表单，Swagger 怎么写？-腾讯云开发者社区-腾讯云

02-同一接口既收 JSON 又收表单，Swagger 怎么写？

02-同一接口既收 JSON 又收表单，Swagger 怎么写？

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐