OpenAPI 概览

Cloud Endpoints 支持使用 受支持版本 的 OpenAPI 规范描述的 API。

您的 API 可以使用任何公开可用的 REST 框架（例如 Django 或 Jersey）实现。

您可以在 JSON 或 YAML 文件（也称为 OpenAPI 文件 ）中描述您的 API。本页面介绍了使用 OpenAPI 的一些好处，展示了一个基本的 OpenAPI 文档，并提供了一些其他信息，旨在帮助您开始使用 OpenAPI。

支持的 OpenAPI 版本

Cloud Endpoints 支持以下 OpenAPI 版本：

  1. OpenAPI 2.0（以前称为 Swagger）
  2. OpenAPI 3.0.x
  3. OpenAPI 3.1.x

您可以从 OpenAPI Initiative 获取每个版本的正式规范。

补丁版本支持

OpenAPI 规范表明，补丁版本（例如 3.0.1、3.0.2）仅引入修复或说明，不会添加新功能。因此，Cloud Endpoints 支持 3.0 和 3.1 的所有补丁版本。

术语

在整个 Cloud Endpoints 文档中，“OpenAPI 3.x”是指所有受支持的 OpenAPI 3 版本。

福利

使用 OpenAPI 的一项主要优势是可以生成文档；获得描述 API 的 OpenAPI 文档后，便可为 API 生成参考文档。

使用 OpenAPI 还有其他好处。例如，您可以：

  • 生成数十种语言版本的客户端库。
  • 生成服务器存根。
  • 使用项目验证您的符合性并生成示例。

OpenAPI 文档的基本结构

OpenAPI 文档描述了 REST API 的表面，并定义了以下信息：

  • API 的名称和说明。
  • API 中的各个端点（路径）。
  • 如何对调用者进行身份验证。

OpenAPI 文档的结构取决于您使用的 OpenAPI 版本。以下示例介绍了 OpenAPI 2.0 和 OpenAPI 3.x 的结构。

OpenAPI 2.0

如果您不熟悉 OpenAPI，请查看 Swagger 基本结构 网站，该网站提供了 OpenAPI 示例文档（也称为 Swagger 规范），并简要说明了该文件的每个部分。以下示例展示了此基本结构：

swagger: "2.0"
info:
  title: API_ID optional-string
  description: "Get the name of an airport from its three-letter IATA code."
  version: "1.0.0"
host: API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
schemes:
  - "https"
paths:
  "/airportName":
    get:
      description: "Get the airport name for a given IATA code."
      operationId: "airportName"
      parameters:
        - name: iataCode
          in: query
          required: true
          type: string
      responses:
        200:
          description: "Success."
          schema:
            type: string
        400:
          description: "The IATA code is invalid or missing."

OpenAPI 3.x

如果您不熟悉 OpenAPI，请查看 OpenAPI 规范，该规范提供了 OpenAPI 示例文档，并说明了该文件的每个部分。

以下示例展示了此基本结构：

openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Get the name of an airport from its three-letter IATA code
  version: 1.0.0
servers:
  - url: https://API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    x-google-endpoint: {}
x-google-api-management:
  backends:
    BACKEND_NAME