OpenAPI 概览

API Gateway 支持使用 OpenAPI 规范 2.0 版描述的 API。您的 API 可以使用任何公开可用的 REST 框架（例如 Django 或 Jersey）实现。

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

优势

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

使用 OpenAPI 还有其他好处。例如，您可以执行以下操作：

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

OpenAPI 文档的基本结构

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

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

如果您刚开始接触 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: DNS_NAME_OF_DEPLOYED_API
    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 中，两者都有相应的开源项目 泽西岛 和 Spring 可使用注释生成 OpenAPI 文档。另外还有 Maven 插件。Python 和 Node 开发者可能会对 OpenAPI.Tools 项目感兴趣。

OpenAPI 社区一直在开发相关工具，旨在帮助人们撰写（对于某些语言，可自动生成）OpenAPI 文档。如需了解详情，请参阅 OpenAPI 规范。

后续步骤