API 端点

上一页展示了 OpenAPI 描述 (OAD) 的最小结构，但没有在 API 中添加任何操作。本页将解释如何操作。

端点列表

API 端点（也称为操作或路由）在 OAS 中被称为 **路径**。路径对象，可以通过根 OpenAPI 对象中的 paths 字段访问，是 API 支持的所有操作的容器

OpenAPI 对象在 OpenAPI 描述的结构页面中进行了说明。

路径对象中的每个字段都是一个路径项对象，它描述一个 API 端点。使用字段而不是数组，是因为它们在语法级别强制执行端点名称的唯一性（任何 JSON 或 YAML 解析器都可以检测错误，而无需 OpenAPI 验证器）。

路径 **必须以正斜杠开头** /，因为它们直接追加到服务器 URL（在 API 服务器页面中描述）以构建完整的端点 URL。

井字棋示例 API 用于本指南中，以举例说明每个概念，并随着指南的进展逐步构建。以下是第一个片段，其中包含一个端点

openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0
paths:
  /board:
    ...

路径项对象

路径项对象描述了可以在路径上执行的 HTTP 操作，每个操作都有一个单独的操作对象。允许的操作与 HTTP 方法名称匹配，例如 get、put 或 delete，列出最常见的方法（在路径项对象规范中查找完整列表）。

此对象还接受所有路径操作的通用属性，例如 summary 或 description。每个操作的详细信息在每个子操作对象中给出。

paths:
  /board:
    get:
      ...
    put:
      ...

操作对象

除了为操作提供 summary 和 description 之外，操作对象主要描述操作的参数、负载和可能的服务器响应。本页的其余部分将解释 responses 字段，而参数和负载将在另一页中处理。

paths:
  /board:
    get:
      summary: Get the whole board
      description: Retrieves the current state of the board and the winner.
      parameters:
        ...
      responses:
        ...

响应对象

响应对象是服务器可以对该请求给出的预期答案的容器。每个字段名称都是一个 **用引号括起来的** HTTP 响应代码，其值是一个响应对象（注意，末尾没有 's'），其中包含有关响应的详细信息。

必须至少给出一种响应，并且建议它与成功情况（通常是 HTTP 响应代码 200）相对应。允许 5 个通配符：1XX、2XX、3XX、4XX 和 5XX（显式代码优先于通配符）。

paths:
  /board:
    get:
      responses:
        "200":
          ...
        "404":
          ...

响应对象

响应对象包含一个 **必需的** description，用于描述响应在该操作的上下文中所代表的含义，补充了 HTTP 响应代码（本质上是通用的）的意义。这有助于开发人员更好地理解如何对该特定代码做出反应。

不过，最重要的字段是 content，因为它描述了响应的可能负载。由于其复杂性，此字段的格式将在单独的页面中详细介绍。

paths:
  /board:
    get:
      responses:
        "200":
          description: Everything went fine.
          content:
            ...

井字棋示例

以下是示例的一部分，其中仅包含迄今为止在指南中介绍的对象。此时，读者应该能够理解此片段中的每一行。

openapi: 3.1.0
info:
  title: Tic Tac Toe
  description: |
    This API allows writing down marks on a Tic Tac Toe board
    and requesting the state of the board or of individual squares.
  version: 1.0.0
paths:
  # Whole board operations
  /board:
    get:
      summary: Get the whole board
      description: Retrieves the current state of the board and the winner.
      responses:
        "200":
          description: "OK"
          content:
            ...

完整的 OpenAPI 描述可以在井字棋示例 API 中找到。

总结

本页介绍了如何指定端点（paths）、它们可用的操作（get、put 等）以及它们可能的结果（responses）。

下一页将介绍如何指定响应的 content。