OpenAPI 概览

API Gateway 支持使用 OpenAPI 规范 2.0 版描述的 API。您的 API 可以使用任何公开可用的 REST 框架(例如 DjangoJersey)实现。

您可以在 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 规范

后续步骤