
> 标签：`#OpenAPI` `#参数位置` `#cookie` `#querystring` `#Swagger2.0`

---

## 实践问题

很多公司的后台，技术架构上采用 SaaS 模式：同一套 API 要同时服务多个租户，网关需要从 Cookie 里取租户 ID 做路由。你在 Swagger 2.0 的文档里翻遍了 `parameters`，却发现 `in` 的取值只有 `query`/`header`/`path`/`formData`/`body`，根本没有 `cookie`。团队只好把租户 ID 写进 `header` ，或者把它塞到 `query` 里——结果 **鉴权信息进了网关日志**。

另一个场景更隐蔽：下游系统要求把整个查询串作为单值透传，比如 `?filter=status%3Dactive%26sort%3Ddesc`。2.0/3.0 的 `query` 只能描述单个键值对参数，无法表达「这一整串查询是一个参数」。你只能在文档注释里写「把整串东西放到 `filter` 里」，对接方全靠猜编码方式。

这两个场景看似不同，本质都是“ **参数能表达的语义，范围不足、能力不够** ”：规范没有给 Cookie 和普通查询串分配正确的「位置」，网关和框架就无法正确解析请求。

---

## API思想进化

**参数的语义边界必须被精确表达——位置与编码方式，决定网关和框架能否正确解析。**

参数不是名字和类型就够了。它从哪来（query/header/path/cookie）、是不是一整串（query vs querystring）、用什么编码（style: cookie 还是普通 percent-encoding），都会影响网关路由、鉴权校验、代码生成和日志脱敏。规范一旦缺了某种位置，真实系统就只能用约定或 hack 来填补，而约定和 hack 是生产事故的重灾区。

---

## 旧写法 vs 新写法

![04-parameter-matrix.png](https://developer.qcloudimg.com/http-save/yehe-11563618/8cca0289a0de92b874948d43c851e7d8.png)

*图：参数位置演进矩阵（2.0 → 3.0 → 3.2）*

### 2.0：参数位置模型缺了两块

Swagger 2.0 的 `parameters.in` 只有五个取值：`query`、`header`、`path`、`formData`、`body`。Cookie 不在普通参数位置里，只能以 `apiKey` 安全方案的形式出现。

来看公开 API **1-OFD API**（Swagger 2.0）的真实写法：

```yaml
swagger: '2.0'
# ...
securityDefinitions:
  cookieAuth:
    type: apiKey
    in: cookie
    name: PLAY_SESSION
  partherApiKeyAuth:
    type: apiKey
    in: header
    name: apikey
```

来源：`https://app.swaggerhub.com/apis/tes426/1-ofd_api/1.0.0`

这说明 2.0 时代不是完全不能写 `cookie`，但**cookie 只能用于安全方案**（`securityDefinitions`），不能作为普通操作参数。如果你的场景是「从 Cookie 取租户 ID 做路由」，2.0 的规范层面就写不出来。

至于「整串查询作为单值」，2.0 完全没有对应机制，只能用 `query` 里的单个字符串参数凑合。

### 3.0：终于有 `in: cookie`

OpenAPI 3.0 去掉 `body`/`formData`，新增 `cookie`，参数类型统一用 `schema` 子对象描述：

```yaml
openapi: '3.0.3'
paths:
  /tenants/{id}/orders:
    get:
      parameters:
        - name: X-Tenant-Id
          in: header
          schema:
            type: string
        - name: sid
          in: cookie
          schema:
            type: string
```

现在网关可以从 Cookie 取会话 ID，框架生成代码时也能识别 `in: cookie`，不再需要口头约定。

### 3.2：`querystring` 与 `style: cookie`

OpenAPI 3.2 进一步补全边界：

- `in: querystring`：将整个查询串作为单个值，必须用 `content` 描述；
- `style: cookie`：遵循 RFC 6265 Cookie 语法，避免百分号编码歧义。

```yaml
openapi: '3.2.0'
paths:
  /search:
    get:
      parameters:
        - name: qs
          in: querystring
          required: true
          content:
            application/x-www-form-urlencoded:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  sort:
                    type: string
        - name: sid
          in: cookie
          style: cookie
          schema:
            type: string
```

`querystring` 与 `query` 互斥：你要么按键值对描述，要么把整串当一个值描述，不能混着来。

![04-query-vs-querystring.png](https://developer.qcloudimg.com/http-save/yehe-11563618/125c9ab5e9c321abc0c3f3efc149a097.png)

*图：in: query 拆多个参数 vs in: querystring 整串单值*

---

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

### 案例 1：1-OFD API —— 2.0 时代 cookie 只能进安全方案

- SwaggerHub 链接：`https://app.swaggerhub.com/apis/tes426/1-ofd_api/1.0.0`
- 关键特征：`securityDefinitions.cookieAuth` 中 `type: apiKey`、`in: cookie`

这个案例非常有代表性：它不是操作参数，而是认证方案。恰恰说明 2.0 的 cookie 被限定在安全领域，普通参数位置没有它的位置。

### 案例 2：Modern Petstore API —— 3.2 的完整参数能力

- SwaggerHub 链接：`https://app.swaggerhub.com/apis/hcm-a45/S3V2/1.0.0`
- 关键特征：OpenAPI 3.2.0，含 `servers`、`requestBody`、`webhooks`、`$self`、Tag `parent` 等

虽然这个 API 没有直接使用 `in: cookie` 或 `in: querystring`，但它是 3.2 能力的集大成者，展示了 3.2 能描述的参数边界远宽于 2.0。

---

## 落地 checklist

1. **2.0 项目需要 Cookie 参数时**，只能用 `securityDefinitions` 里的 `apiKey` + `in: cookie` 做认证，无法描述普通 Cookie 参数；迁移到 3.0+ 后再引入 `in: cookie`。
2. **3.0+ 普通 Cookie 参数用 `in: cookie`**，参数值用 `schema` 描述，别再写进 `header` 靠约定。
3. **3.2 的 Cookie 参数建议加 `style: cookie`**，遵循 RFC 6265，避免编码歧义。
4. **整串查询用 `in: querystring`**，且必须与 `in: query` 互斥；用 `content` 描述整串的 schema。
5. **不要把鉴权信息放进 `query` 参数**，会进网关日志；Cookie 或 Header 是更安全的位置。
6. **网关和框架升级要跟上**：用了 `in: cookie` 或 `in: querystring` 后，确保网关解析器和代码生成器支持 3.0/3.2。

---

## 下一篇预告

OpenAPI演进录 | 05-OpenAPI 3.1 这次不兼容升级，可选字段全变必填

标签：#OpenAPI #参数位置 #cookie #querystring #Swagger2.0

OpenAPI演进录 | 04-Cookie参数和整串查询，旧版OpenAPI写不了？

聊聊开放 API 的 Swagger 描述规范。这 11 篇文章以「OpenAPI 演进录」为主线，系统梳理了从 Swagger 2.0 到 OpenAPI 3.2 的规范演进与工程实践，讲解如何用契约准确描述真实 API 中的环境、内容协商、复用、参数、可空、多态、事件、流式、安全与治理等复杂场景。

开发工具

后端

网络与通信

"OpenAPI规范演进解决参数位置难题：Swagger2.0缺失Cookie和整串查询参数支持，3.0新增in:cookie，3.2引入in:querystring和style:cookie。规范升级让网关路由、鉴权校验更精准，避免鉴权信息泄露日志。了解参数位置演进对API设计、代码生成和系统安全至关重要。"

代码解释

路由

SaaS

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

OpenAPI演进录 | 04-Cookie参数和整串查询，旧版OpenAPI写不了？-腾讯云开发者社区-腾讯云

OpenAPI演进录 | 04-Cookie参数和整串查询，旧版OpenAPI写不了？

OpenAPI演进录 | 04-Cookie参数和整串查询，旧版OpenAPI写不了？

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐