メインコンテンツまでスキップ

OpenAPI とは何ですか?

OpenAPI とは、RESTful API を設計、記述、共有するための標準的な仕様のことです。以前は「Swagger 仕様」として知られていましたが、現在では OpenAPI Initiative (OAI)によって管理されています。OpenAPI を使うことで、API の設計書を統一された形式で記述でき、開発者やツールがそれを利用しやすくなります。

OpenAPI の用途​

  1. API の設計
    OpenAPI を使うと、API のエンドポイント、リクエスト/レスポンスの形式、認証、エラーコードなどを事前に定義することができます。

  2. ドキュメントの生成
    OpenAPI の定義ファイル（通常 openapi.yaml または openapi.json）から、API のドキュメントを自動生成することができます。これにより、開発者が API を理解しやすくなります。

  3. コード生成
    OpenAPI 定義を使って、サーバー側やクライアント側のコードを自動生成できます。例えば、Python や Java、JavaScript などで API のリクエストを行うコードや、サーバーのスケルトンを生成することができます。

  4. テストの効率化
    定義を基に API の動作テストを自動化するツールと連携可能です。

  5. チーム間のコミュニケーションの向上
    API 設計が明確に定義されているため、開発者、QA、プロダクトマネージャーなどのチームメンバー間での共通認識が持てます。

OpenAPI の基本的な使い方​

1. インストールとツールの準備​

  • OpenAPI 定義ファイルを作成するには、エディターやツールを使用します。おすすめのツール：
    • Swagger Editor（ブラウザで利用可能）
      URL: https://editor.swagger.io/
    • VS Code 用プラグイン（Swagger Viewerなど）
    • Postman（API 設計を GUI で作成可能）

2. 基本構造の理解​

OpenAPI 定義は、YAML または JSON 形式で記述します。以下は簡単な例です：

openapi: 3.0.0
info:
  title: サンプルAPI
  version: 1.0.0
paths:
  /users:
    get:
      summary: ユーザーのリストを取得
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

3. 定義ファイルの作成​

  • 上記のように、API のエンドポイントやリクエスト/レスポンスのフォーマットを記述します。

4. ドキュメントの生成​

  • Swagger UI や ReDoc などのツールを使うことで、定義ファイルから読みやすいドキュメントを生成できます。

5. コード生成​

  • OpenAPI GeneratorやSwagger Codegenを使用して、以下を自動生成できます：
    • サーバースケルトンコード
    • クライアント SDK
    • API のスタブ（モックサーバー）
# 例: Javaのクライアントコードを生成
openapi-generator-cli generate -i openapi.yaml -g java -o ./client

6. テストの実行​

  • OpenAPI 定義を用いて API のテストを実行するツール（例：Postman、Prism）と連携することで、スムーズにテストが行えます。

OpenAPI を学ぶためのリソース​

にMacshionが最終更新