OpenAPI 概览

Cloud Endpoints 支持使用 OpenAPI 规范 2.0 版描述的 API。 您的 API 可以使用任何公开可用的 REST 框架（例如 Django 或 Jersey）实现。您可以在 JSON 或 YAML 文件（也称为 OpenAPI 文件）中描述您的 API。本页面介绍了使用 OpenAPI 的一些好处，展示了一个基本的 OpenAPI 文档，并提供了一些其他信息，旨在帮助您开始使用 OpenAPI。

优势

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

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

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

OpenAPI 文档的基本结构

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

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

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

    swagger: "2.0"
    info:
      title: "Airport Codes"
      description: "Get the name of an airport from its three-letter IATA code."
      version: "1.0.0"
    # This field will be replaced by the deploy_api.sh script.
    host: "YOUR-PROJECT-ID.appspot.com"
    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.yaml 文件还演示了以下内容：

生成 OpenAPI 文档

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

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

后续步骤