【入門編】 OpenAPI Specification (OAS) 3.0/3.1の構造と記述ルール – Web APIアーキテクチャ・データ連携実践ガイド

APIの世界にも「住所録」が必要だ！OpenAPI（OAS）で迷子にならない設計術

ネットワークの世界に飛び込んだばかりの皆さん、こんにちは。

皆さんは普段、郵便物を受け取るとき、送り主が宛先をめちゃくちゃに書いていたらどう思いますか？「これ、どこに届ければいいんだ？」と困り果ててしまいますよね。実は、Web APIの世界も全く同じなんです。

今回は、APIという「荷物」を正確に届けるためのルールブック、OpenAPI Specification（OAS）について、インフラエンジニアの視点から紐解いていきたいと思います。難しい仕様書の山を読み解く前に、まずは「なぜこれが必要なのか」という本質から見ていきましょう。

—

1. OpenAPIは「API界の地図兼住所録」

私たちが普段使っているWebサービスは、裏側でたくさんのサーバーが会話をしています。例えば、「ユーザー情報を教えて！」と頼んだら、「はい、これがユーザー情報ですよ」とデータが返ってくる。このやり取りのルールを定めたものがAPIです。

しかし、このルールがバラバラだとどうでしょう。ある人は「名前」を name と呼び、ある人は full_name と呼ぶ。これでは、システムが混乱してしまいますよね。

そこで登場するのが OpenAPI Specification (OAS) です。これは、「このAPIにはどんな機能があって、どんな形式のデータを送ればいいか」を誰が見てもわかるように記した共通の設計図のこと。いわば、巨大なビル（システム）に設置された、完璧な案内板のようなものです。

—

2. OpenAPIの「3つの重要パーツ」を読み解く

OpenAPIの定義ファイル（YAMLやJSON形式）は、大きく分けて3つのパーツで構成されています。まずはこれだけ覚えれば、全体像はバッチリです。

① paths：郵便配達のルート案内

ここには、「どのURLにアクセスすると、何ができるか」が書かれています。

paths:
  /users: # このURLへのアクセスを定義します
    get:
      summary: ユーザー一覧を取得する
      responses:
        '200':
          description: 成功！ユーザーリストを返します

「/users に GET（取得）でアクセスすれば、ユーザー一覧がもらえるよ」という、まさにルート案内ですね。

② components：部品の倉庫

APIを作っていると、「ユーザーID」や「エラーメッセージ」など、何度も同じデータ構造を使う場面が出てきます。これらを毎回書き直すのは非効率ですし、間違いの元です。そこで components という倉庫にまとめておきます。

components:
  schemas:
    User: # ユーザーという「型」を定義
      type: object
      properties:
        id:
          type: integer # IDは数字ですよ
        name:
          type: string  # 名前は文字ですよ

こうしておけば、「ユーザーの情報が必要なときは、この User 型を使ってね」と共通認識を持てるようになります。

③ schemas：データの「梱包ルール」

components の中で定義される schemas は、荷物の中身（データ形式）を厳格に決める役割です。数字なのか、文字列なのか、必須項目なのか。これを決めることで、受信側のシステムは「あ、これはIDだから数字として処理しよう」と迷わず動けます。

—

3. 実践！一貫性のある美しいAPI設計のコツ

API設計で最も大切なのは、「いつ、誰が作っても同じルールになること」です。現場でよく使う、一貫性を保つための「3つの鉄則」を紹介します。

リソース名は複数形かつ名詞にする
/user ではなく /users。APIは「モノ」を扱うので、集合体として扱うのが基本です。
HTTPメソッドを正しく使う
GET（取得）、POST（作成）、PUT（更新）、DELETE（削除）。これらは郵便でいうところの「書留」「速達」のような配送種別です。目的と手段を一致させましょう。
ステータスコードを明確に
200 OK だけではなく、エラー時には 400 Bad Request（入力ミス）や 404 Not Found（場所が違う）を使い分けることで、トラブルシューティングが劇的に楽になります。

—

最後に：完璧を目指さず、まずは「標準」から

駆け出しの頃は、「どんな設計が正解なんだろう？」と悩みすぎることもあるかもしれません。でも安心してください。OpenAPIを使う最大のメリットは、「設計図をコードから自動生成できること」にあります。

自分で複雑なドキュメントを一から書くのではなく、まずはツール（Swagger Editorなど）を使って、先ほど紹介した paths や components を少しずつ埋めてみてください。

ネットワークのパケットが迷わず目的地へ届くように、APIもまた、正しい設計図があれば誰にとっても使いやすいサービスになります。皆さんの書くAPI定義が、誰かの開発を助ける素晴らしい「道しるべ」になりますように！

それでは、次回の記事でお会いしましょう。Happy Coding!