3. 路径与操作定义：路径对象、操作对象与核心标记

路径与操作是 OpenAPI 文档的骨架。路径对象（Path Object）定义 API 的端点 URL 模板，操作对象（Operation Object）描述该端点上允许的 HTTP 方法及其语义。本章聚焦路径与操作的结构化定义，包括 operationId、summary、description 和 deprecated 标记，确保接口文档既机器可读又人类可理解。

3.1 路径对象（Path Object）

路径对象是 OpenAPI 文档中 paths 字段下的键值对。键是相对路径模板（如 /users/{userId}），值是该路径上所有 HTTP 方法的操作描述。路径模板支持 {参数名} 格式的路径参数，用于动态路由。

3.2 操作对象（Operation Object）

操作对象定义单个 HTTP 方法的具体行为。每个操作对象包含请求参数、请求体、响应定义、安全要求等核心信息。以下是操作对象的关键字段：

• operationId —— 操作的唯一标识符，用于代码生成和日志追踪，必须全局唯一
• summary —— 操作的简短标题（如“获取用户列表”），用于文档目录和 API 客户端
• description —— 操作的详细说明，可包含使用场景、业务规则、前置条件等
• deprecated —— 布尔值标记，指示该操作是否已废弃，默认 false
• parameters —— 操作级别的参数列表，覆盖路径级别的同名参数
• requestBody —— 仅适用于 POST / PUT / PATCH，描述请求体结构
• responses —— 必须字段，定义所有可能的 HTTP 状态码响应

3.3 GET / POST / PUT / DELETE 语义对比

3.4 deprecated 标记与版本管理

deprecated 标记用于告知 API 消费者该操作即将移除，应迁移到替代方案。在 OpenAPI 3.x 中，deprecated 可应用于操作对象、参数、模式属性等多个层级。标记为 true 的操作仍可正常调用，但文档和工具应提示使用者避免新集成。

• 操作级别： deprecated: true 表示整个端点方法废弃
• 参数级别： 某个查询参数或路径参数废弃
• 属性级别： 响应或请求体中的某个字段废弃

3.5 路径与操作定义示例

paths:
  /users/{userId}:
    get:
      operationId: getUserById
      summary: 根据用户 ID 获取用户详情
      description: 返回指定用户的完整信息，包括姓名、邮箱、角色等。
      deprecated: false
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功返回用户对象
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 用户不存在
    delete:
      operationId: deleteUser
      summary: 删除指定用户
      description: 软删除用户，保留数据 30 天后物理清除。
      deprecated: true
      responses:
        '204':
          description: 删除成功，无返回内容
        '404':
          description: 用户不存在

3.6 路径与操作结构图

3.7 操作对象字段速查表

3.8 路径与操作定义检查清单

• 路径命名：使用名词复数，避免动词，路径参数用 {} 包裹
• operationId 唯一性：全局不重复，推荐 动词+名词 格式
• summary 简洁性：控制在 60 字符以内，能独立描述操作目的
• description 完整性：包含业务规则、前置条件、错误场景说明
• deprecated 迁移指引：废弃操作必须注明替代方案和移除时间
• 方法语义正确：GET 无请求体，POST 非幂等，PUT/DELETE 幂等
• 参数层级：路径级别参数用于公共参数，操作级别参数用于方法特有参数