3. 路径与操作：定义API端点、HTTP方法、操作ID、标签与分组

路径（Path）与操作（Operation）是OpenAPI规范的核心骨架。路径定义了API暴露的端点（Endpoint），操作则描述了在该端点上允许的HTTP方法及其行为。本章将深入讲解如何规范地定义路径、选择HTTP方法、分配操作ID（operationId）、以及使用标签（Tags）进行逻辑分组。

3.1 路径定义：端点结构

在OpenAPI中，路径以/开头，支持静态路径与动态路径参数。路径参数使用花括号{}包裹，并在parameters字段中声明。

路径设计原则：
  • 使用名词复数形式表示资源（如 /users、/orders）。
  • 路径层级不宜过深，建议不超过3层。
  • 路径参数应语义明确，避免歧义。
paths:
  /users:
    get:
      summary: 获取用户列表
      operationId: listUsers
    post:
      summary: 创建新用户
      operationId: createUser
  /users/{userId}:
    get:
      summary: 获取单个用户
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
    put:
      summary: 更新用户信息
      operationId: updateUser
    delete:
      summary: 删除用户
      operationId: deleteUser

3.2 HTTP方法选择与语义

每个路径下可定义多个操作，每个操作对应一个HTTP方法。常用方法及其语义如下：

HTTP方法 CRUD对应 幂等性 请求体 典型场景
GET Read 是 无 查询资源列表或详情
POST Create 否 有 创建新资源、提交操作
PUT Update/Replace 是 有 全量更新资源
PATCH Partial Update 否 有 部分更新资源
DELETE Delete 是 无 删除资源
最佳实践： 对于非CRUD操作（如激活、暂停），优先使用POST + 动作路径（如 /users/{userId}/activate），而非在GET或PUT中附加副作用。

3.3 操作ID（operationId）

operationId 是操作的唯一标识符，在整个API文档中必须唯一。它常用于生成客户端SDK的方法名、日志追踪以及文档锚点。

paths:
  /orders:
    get:
      operationId: listOrders      # 推荐：动词 + 资源复数
      summary: 获取订单列表
    post:
      operationId: createOrder     # 推荐：动词 + 资源单数
      summary: 创建订单
  /orders/{orderId}:
    get:
      operationId: getOrderById    # 推荐：动词 + 资源 + By + 参数
      summary: 根据ID获取订单
    delete:
      operationId: deleteOrder     # 推荐：动词 + 资源
      summary: 删除订单
避坑指南： 避免使用模糊的operationId，如 getData、process。建议采用 <动词><资源>[By<参数>] 的命名模式，确保在代码生成和API文档中清晰可辨。

3.4 标签与分组

标签（Tags）用于对操作进行逻辑分组，在API文档中通常表现为分组标题。一个操作可以关联多个标签，但通常只使用一个主要标签。

paths:
  /users:
    get:
      tags:
        - 用户管理
      operationId: listUsers
      summary: 获取用户列表
    post:
      tags:
        - 用户管理
      operationId: createUser
      summary: 创建用户
  /orders:
    get:
      tags:
        - 订单管理
      operationId: listOrders
      summary: 获取订单列表
  /users/{userId}/orders:
    get:
      tags:
        - 订单管理
        - 用户管理
      operationId: listUserOrders
      summary: 获取指定用户的订单列表

标签也可以在顶层tags字段中预先定义，并添加描述信息：

tags:
  - name: 用户管理
    description: 用户相关的增删改查操作
  - name: 订单管理
    description: 订单查询与创建操作

3.5 路径与操作结构总览

下图展示了路径、HTTP方法、操作ID与标签之间的层级关系：

路径与操作结构总览 OpenAPI 规范 路径 /users 路径 /orders GET listUsers POST createUser GET listOrders POST createOrder 标签：用户管理 标签：订单管理 核心关系 规范 → 路径 → 操作(HTTP方法 + operationId) → 标签(分组)

3.6 路径参数与查询参数

路径参数（Path Parameters）是URL路径的一部分，而查询参数（Query Parameters）附加在URL末尾。两者在OpenAPI中的定义方式不同：

参数类型 位置 示例 是否必须 典型用途
路径参数 in: path /users/{userId} 是 资源标识符
查询参数 in: query /users?page=1&size=20 否 过滤、分页、排序
请求头参数 in: header Authorization: Bearer xxx 视情况 认证、内容协商 
paths:
  /users:
    get:
      operationId: listUsers
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            default: 20
  /users/{userId}:
    get:
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer

3.7 标签分组与API文档导航

合理的标签分组能显著提升API文档的可读性。下图展示了标签如何影响文档的导航结构：

标签分组与文档导航 无标签分组（混乱） GET /users POST /orders DELETE /users/{userId} GET /orders/{orderId} POST /users 有标签分组（清晰） 用户管理 GET /users POST /users DELETE /users/{userId} 订单管理 POST /orders GET /orders/{orderId}
标签分组建议：
  • 按业务领域分组（如用户管理、订单管理、支付管理）。
  • 每个操作只关联一个主要标签，避免交叉混乱。
  • 在顶层 tags 字段中为每个标签添加描述，提升文档可读性。

3.8 常见错误与避坑

错误类型 错误示例 正确做法
路径参数未声明 /users/{id} 但未定义 parameters 在操作或路径级别声明 parameters
operationId 重复 两个操作都使用 getData 确保全局唯一，如 getUserById、getOrderById
HTTP方法误用 用GET创建资源 创建用POST，查询用GET
标签滥用 一个操作关联5个标签 每个操作最多关联1-2个标签
关键提醒： 路径与操作的定义是API契约的基石。一旦发布，修改路径或operationId将导致客户端代码断裂。建议在开发初期使用API设计工具（如Swagger Editor、Stoplight）进行可视化验证，确保路径结构、方法语义和标签分组符合团队规范。
← 上一章 📖 返回目录 下一章 →