3. 定义第一个API端点

在OpenAPI规范中，路径（Path）与HTTP方法（Method）构成了API端点的骨架。路径标识资源的位置，方法定义对该资源执行的操作。本节将系统讲解如何定义第一个端点，包括路径设计、四种核心HTTP方法、请求参数分类以及响应对象与状态码的规范写法。

3.1 路径与HTTP方法的核心组合

OpenAPI使用paths对象作为顶级容器，每个路径下可定义多个HTTP方法。路径以/开头，支持静态路径和带参数的动态路径。四种最常用的HTTP方法对应CRUD操作：

3.2 请求参数的四种来源

OpenAPI规范将请求参数按位置分为四类：path、query、header、cookie。每个参数必须声明name、in、required和schema。

3.3 响应对象与状态码

每个操作必须定义至少一个响应。响应对象包含description和可选的content（描述响应体结构）。状态码使用HTTP标准码，OpenAPI支持使用default作为兜底响应。

常见响应状态码分类：

• 2xx 成功：200（OK）、201（Created）、204（No Content）
• 3xx 重定向：301（Moved Permanently）、304（Not Modified）
• 4xx 客户端错误：400（Bad Request）、401（Unauthorized）、403（Forbidden）、404（Not Found）、422（Unprocessable Entity）
• 5xx 服务端错误：500（Internal Server Error）、502（Bad Gateway）、503（Service Unavailable）

3.4 完整端点定义示例

以下是一个完整的OpenAPI 3.0端点定义，包含路径参数、查询参数、请求体、响应对象和多种状态码：

paths:
  /users/{userId}:
    get:
      summary: 根据ID获取用户信息
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
        - name: fields
          in: query
          required: false
          schema:
            type: string
            enum: [basic, detail, all]
            default: basic
        - name: X-Request-Id
          in: header
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 成功返回用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: 请求参数校验失败
    post:
      summary: 创建新用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 用户创建成功
          headers:
            Location:
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '422':
          description: 请求体校验失败

3.5 端点设计流程

下图展示了从资源识别到OpenAPI端点定义的标准流程：

3.6 参数定义规范与避坑

定义参数时需遵循以下规范：

• 命名风格：路径参数使用驼峰（userId），query参数使用蛇形（page_size），保持团队一致。
• 参数校验：使用schema中的minimum、maximum、pattern、enum等约束，避免在文档中仅用文字描述校验规则。
• 可选参数默认值：为query参数设置default值，减少客户端传参负担。
• Header参数前缀：自定义header建议使用X-前缀（如X-Request-Id），但标准header（如Authorization）不要加前缀。

3.7 响应对象的结构化设计

响应对象应包含统一的包装结构，便于客户端处理。推荐使用以下模式：

components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          description: 业务状态码，0表示成功
        message:
          type: string
          description: 提示信息
        data:
          description: 实际业务数据
        requestId:
          type: string
          format: uuid
          description: 请求追踪ID
      required:
        - code
        - message
        - requestId

这种统一响应结构使得客户端可以统一解析code和message，而data字段承载具体业务数据。对于错误响应，data字段可包含详细的错误详情列表。