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
      address: https://BACKEND_URL/airportNameGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
x-google-backend: BACKEND_NAME
paths:
  /airportName:
    get:
      summary: Get the airport name for a given IATA code
      operationId: airportName
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string
      parameters:
        - name: iataCode
          in: query
          required: true
          schema:
            type: string

除了基本结构，教程中使用的示例代码中的 openapi.yaml 文件还演示了以下内容：

生成 OpenAPI 文档

根据您使用的语言，您也许能够生成 OpenAPI 文档。在 Java 中，有适用于 Jersey 和 Spring 的开源项目，这些项目可根据注释生成 OpenAPI 文档。另外还有 Maven 插件。Python 用户可能会对 flask-swagger 项目感兴趣，而 Node 开发者可能会对 swagger-node-express 感兴趣。

OpenAPI 社区一直在开发相关工具，旨在帮助人们撰写（对于某些语言，可自动生成）OpenAPI 文档。如需获取工具和集成的完整列表，请参阅 Swagger 网站。

后续步骤