API設計

OpenAPI おーぷんえーぴーあい

API仕様REST APISwaggerスキーマ定義API設計ドキュメント自動生成
OpenAPIについて教えて

簡単に言うとこんな感じ!

OpenAPIはAPIの「取扱説明書の書き方ルール」だよ!「このAPIにこう聞いたらこう返ってくる」っていう仕様を決まった形式で書いておくと、ドキュメントやコードが自動で作れちゃうんだ。開発チームの共通語みたいなものだね!


OpenAPIとは

OpenAPI(オープンエーピーアイ)とは、REST API(Webサービス同士が通信するための仕組み)の仕様を記述するための標準フォーマットのことです。もともとは「Swagger(スワッガー)」という名前でSmartBear社が開発しましたが、2016年にLinux Foundationの傘下に設置されたOpenAPI Initiative(OAI)に寄贈され、オープンな標準規格として整備されました。

YAMLまたはJSONという形式のテキストファイルで「どんなURLに・どんなデータを送ると・どんなデータが返ってくるか」を定義します。この定義ファイル(OpenAPI定義ファイルまたはOpenAPIスペック)があれば、APIのドキュメントを自動生成したり、プログラムの雛形コードを自動生成したり、APIのテストを自動化したりすることができます。

システム発注の現場では、「APIの仕様書をOpenAPIで書いてもらう」と指定することで、開発会社ごとにバラバラなフォーマットで資料が出てくる問題を防ぎ、後々の改修・引き継ぎ・テストが格段にスムーズになります。


OpenAPIの構造と仕組み

OpenAPI定義ファイルは、以下の主要なセクションで構成されます。

セクション役割具体例
infoAPIの名前・バージョン・説明”顧客管理API v1.2”
serversAPIのベースURLhttps://api.example.com/v1
pathsエンドポイント(URLのパス)と操作の定義/customers にGETでリスト取得
components/schemasデータ構造の定義(再利用可能)Customer: id, name, email
security認証・認可の方式APIキー、OAuth2など
tagsエンドポイントのグルーピング”顧客管理”、“注文管理” など

実際の定義ファイルのイメージ

openapi: 3.1.0
info:
  title: 顧客管理API
  version: "1.0"
paths:
  /customers:
    get:
      summary: 顧客一覧を取得する
      responses:
        "200":
          description: 取得成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Customer"
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

OpenAPIのバージョン

現在広く使われているのは以下の2系統です。

バージョン通称特徴
OpenAPI 2.0Swagger 2.0旧来システムで多く使われる。Swagger時代の名残
OpenAPI 3.0.xOAS3現在の主流。表現力が大幅に向上
OpenAPI 3.1.0OAS3.1JSON Schema完全準拠。最新標準

歴史と背景

  • 2010年 — Wordnik社のTony Tam氏がSwaggerを開発。REST APIのドキュメント作成の煩雑さを解消するために生まれた
  • 2015年 — SmartBear社がSwaggerを買収。ツールエコシステムを整備し普及が加速
  • 2016年 — SmartBear社がSwagger仕様をLinux Foundation傘下のOpenAPI Initiativeに寄贈。「Swagger 2.0」が「OpenAPI 2.0」に改名。Google・Microsoft・IBMなど主要企業が参加
  • 2017年 — OpenAPI 3.0.0リリース。認証まわりやスキーマ表現が大幅に強化
  • 2021年 — OpenAPI 3.1.0リリース。JSON Schemaと完全互換になり、WebhookやPathItemの再利用も可能に
  • 現在 — AWS・Azure・GCP など主要クラウドのAPIゲートウェイがOpenAPIに対応。事実上のREST API仕様記述の業界標準となっている

関連ツール・技術との比較

OpenAPIは「仕様を書くルール」であり、その定義ファイルを活用するツール群が充実しています。

OpenAPI定義ファイルを中心としたエコシステム OpenAPI定義ファイル (openapi.yaml / openapi.json) ドキュメント生成 Swagger UI Redoc コード自動生成 OpenAPI Generator Swagger Codegen テスト・バリデーション Postman Spectral / Prism APIリファレンスが 自動で出来上がる クライアント・サーバーの 雛形コードが生成される 仕様との差異を 自動検出できる AWS API Gateway / Azure API Management にインポートしてそのままAPIを公開できる

OpenAPIとGraphQLの違い

比較項目OpenAPI(REST)GraphQL
通信方式HTTPメソッド(GET/POST/PUT等)基本的にPOSTのみ
データ取得エンドポイントごとに固定クライアントが欲しいフィールドを指定
学習コスト低め(概念が直感的)やや高め(独自クエリ言語あり)
仕様記述OpenAPI定義ファイルGraphQLスキーマ
向いている用途汎用的なAPI全般複雑なデータ取得・フロント主導開発

発注時のチェックポイント

✅ 「OpenAPI 3.0以上の定義ファイルを納品物に含めること」を仕様書に明記する
✅ Swagger UIなどで定義ファイルを開いて仕様と実装の一致を確認する
✅ OpenAPI Generatorを使ってSDK(利用側のコード)が生成できる状態を要件にする
✅ CI/CDパイプラインにSpectralなどのLintツールを組み込んで品質を保つ

関連する規格・RFC

規格・RFC番号内容
OpenAPI Specification 3.1.0OpenAPI Initiative が策定する最新の公式仕様
RFC 7231HTTP/1.1のセマンティクス(GETやPOSTなどのメソッド定義)
RFC 7807REST APIのエラーレスポンス形式の標準(Problem Details)
RFC 6749OAuth 2.0(OpenAPIのsecurityセクションで多用される認証方式)

関連用語

  • REST API — URLとHTTPメソッドを使ってデータをやり取りするAPI設計スタイル
  • API — ソフトウェア同士が機能を呼び出し合うための接続口
  • JSON — OpenAPI定義ファイルの記述形式の一つ。軽量なデータ交換フォーマット
  • YAML — OpenAPI定義ファイルで最もよく使われる人間に読みやすい記述形式
  • Swagger — OpenAPIの旧称およびOpenAPIツール群のブランド名
  • APIゲートウェイ — APIの入口を一元管理するミドルウェア。OpenAPIをインポートして使える
  • GraphQL — REST APIの代替となるクエリ言語ベースのAPI通信方式
  • OAuth — APIの認可(アクセス権限の委譲)に使われる標準プロトコル

シス担のミカタ メールマガジン

セキュリティの速報とシステムの最新情報をメールで受け取る

登録すると、次の配信からお届けします。配信はメールの下のリンクから、いつでも解除できます。個人情報の取り扱い