【技術ブログ】OpenAPIの書き方とは？：OpenAPIを使用した設計の知識 vol.2 – Cloud - Flight Attendant

開発エンジニアのMASAE.Mです。

前回記事（【技術ブログ】OpenAPIとは？基本概念とできること：OpenAPIを使用した設計の知識 vol.1）では、OpenAPIでできることをご紹介しました。

今回は、OpenAPIの具体的な書き方と、API仕様書（定義ファイル）を構成する主要な要素について詳しくご紹介いたします。

3. OpenAPIの記述形式

OpenAPIはYAMLかJSONで記述します。
Web検索をするとYAMLで記述している解説が一般的ですが、本記事ではデータ構造の可視性やJSONならではの記述ルールを確認するため、サンプルはJSONで記述します。

実際にAPIでやり取りするデータのイメージがわきやすいというメリットもあるので、JSON派の方もそうでない方も、ぜひ参考にしてみてください。

4. OpenAPIの基本構造

4.1 基本構造

商品情報を管理するシステムで、商品情報を取得するAPIの作成を想定します。
OpenAPIの基本の構造がこちらになります。
赤文字が作成するAPIに合わせて変更する値の部分です。

{
  "openapi": "3.1.0",
  "info": {
    "title": "商品管理API",
    "description": "商品管理のAPI",
    "version": "1.0.0"
  },
  "servers": [
    {"url": "http://localhost:8080"}
  ],
  "tags": [
    {
      "name": "Products",
      "description": "商品"
    }
  ],
  "paths": {
  },
  "components": {
  }
}

openapi：OpenAPIのバージョン
info：APIの名前や説明、バージョン
servers：APIを提供しているサーバー。本番環境や検証環境など複数を定義することが可能
tags：APIを整理するためのタグを定義する。タグは複数定義することが可能
paths：APIの具体的な内容。詳細は4.2に記載
components：複数のAPI操作で共通のパラメータや応答の構造を定義する。詳細は4.3に記載

4.2 Pathsの詳細

このAPIは指定された商品の情報を返す処理になります。

{
  "paths": {
    "/product/{productId}": {
      "get": {
        "summary": "商品情報取得",
        "tags": [
          "Products"
        ],
        "deprecated": false,
        "operationId": "getProduct",
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "description": "商品ID",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "商品情報取得成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                },
                "example": {
                  "id": 1223,
                  "name": "Sample Product",
                  "price": 1000
                }
              }
            }
          },
          "400": {
            "description": "リクエストエラー"
          }
        }
      }
    }
  }
}

"/product/{productId}"：API実行するときのパス。{productId}は実行時に入力値を渡す。処理として入力値が不要な場合は、パスにも{productId}を付ける必要はない。
"get"：データの取得を表す。ほかにpostやdeleteなどがある
"tags"：pathsの前に定義したtagsのタグを指定
"parameters"："/product/{productId}"のproductIdに入力されるべき値を定義
"responses"：APIが返す値の定義。
"200"、"400"：レスポンスのコード
"schema"：レスポンスの構成
"examples"：レスポンスのサンプル
"$ref": "#/components/schemas/Product"：再利用できるように別のところで定義したデータの構成を呼び出している。データの構成は次に記載

4.3 componentsの詳細

レスポンスで参照する商品データの項目を定義しています。

 "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "price": {
            "type": "integer"
          }
        }
      }
    }
  }
}

"schemas"：データモデルを定義する。ほかの定義にresponsesやexamplesがある
"Product"：データモデルの名前
"properties"：データモデルの定義内容。サンプルは、レスポンスで返す商品データの項目の定義

まとめ

OpenAPIの書き方をご紹介しました。
定義書の書き方を合わせることで開発のメンバーが増えたり替わったりした際にも意思疎通がしやすくなります。ここで紹介したのは基本的な項目で、他にも項目はありますのでSwaggerのサイトなどをご活用ください。
次回はOpenAPIのテストについてご紹介いたします。

このように当社ではGoogle関連のサービスを活用したアプリケーション開発を行い、Google Cloud・Google Workspaceをより便利にご利用いただけるようなお手伝いをしています。Google プロダクトを利用する上でのお困りごとがあればお気軽にご相談ください。

※本記事の情報および画像は 2026/02/17 時点での仕様のものです。

3. OpenAPIの記述形式

4. OpenAPIの基本構造

4.1 基本構造

4.2 Pathsの詳細

4.3 componentsの詳細

まとめ

関連記事