OpenAPI の概要

API Gateway は、OpenAPI 仕様のバージョン 2.0 を使用して記述された API をサポートします。作成した API を実装するには、一般公開されている任意の REST フレームワーク（Django や Jersey など）を使用できます。

API は、OpenAPI ドキュメントと呼ばれる YAML ファイルの中に記述されます。ここでは、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 の場合、Jersey と Spring の両方でアノテーションから OpenAPI ドキュメントを生成できるオープンソース プロジェクトがあります。また、Maven プラグインも用意されています。Python や Node のデベロッパーにとって、OpenAPI.Tools は興味深いプロジェクトとなる可能性があります。

OpenAPI コミュニティは、OpenAPI ドキュメントの生成（一部の言語では自動生成）に役立つツールを継続的に開発しています。詳細については、OpenAPI 仕様をご覧ください。

次のステップ