OpenAPI

📖 もうちょい詳しく

何が新しいの？

サービス同士をつなぐ窓口であるAPIは、「どんな住所に、どんな形のデータを送れば、何が返ってくるか」をきちんと取り決めておく必要があります。その取り決めを、人が読む説明書としてだけでなく、機械もそのまま読み取れる形で書きそろえる決まりが OpenAPI です。もともとは Swagger（スワッガー）という名前で広まり、のちに OpenAPI と改められました。いまでは REST API の仕様を書く標準として、広く使われています。

どうやって動いてるの？

OpenAPI では、APIの中身を YAML や JSON という決まった書き方のテキストにまとめます。どんな入口（エンドポイント）があり、どんな項目を送り、どんな形で返るか、を1つのファイルに整理して書く形です。このファイルは決められたルールに沿っているので、対応するツールに読み込ませれば、内容を自動で解釈できます。人が眺めても分かり、機械もそのまま処理できる、という二面を持っているのが特徴です。

何ができるの？

書きそろえた仕様ファイルから、見やすいAPIの説明ページを自動で作れます。さらに、その仕様を呼び出すためのプログラム（クライアントコード）も、いくつかの言語で自動生成できます。手書きの説明書とプログラムがずれていく、というありがちな問題を抑えやすくなります。

🌱 身近なたとえ

役所の申請書の「記入例つき様式」で例えると、分かりやすいかもしれません。どの欄に何を書くか、どんな形で返事が来るかが、ひとつの様式にきっちり決まっていますよね。OpenAPI も同じで、APIの使い方をひとつの様式にまとめておく約束事です。様式がそろっているからこそ、案内冊子を自動で刷ったり、受付の仕組みを下ごしらえしたりできます。

✅ まず覚えるポイント

• REST APIの仕様を書きそろえる、標準のフォーマットです
• 仕様は YAML や JSON で書き、人にも機械にも読めます
• 旧称は Swagger で、のちに OpenAPI と改められました
• 仕様からAPIの説明ページを自動で作れます
• 仕様から呼び出し用のコードも自動生成できます

🧭 よくある勘違い

OpenAPI はAPIそのものなの？

APIを動かす本体ではなく、「APIをどう使うか」を書き表すための決まりごとです。実際にデータを返すのは、別に用意したプログラムの役目になります。OpenAPIは、その使い方を整理した仕様書を作るための共通ルール、と考えると正確です。

Swagger とは別物なの？

もとは同じものです。Swagger という名前で広まった仕様が、のちに OpenAPI へと改名されました。いまでも Swagger は、その仕様を扱う道具（説明ページを作るツールなど）の名前として残っているので、名前が混ざって見えることがあります。

🧩 関連して覚えると楽な言葉

• REST: OpenAPIが主な対象にする、APIの設計スタイルのひとつ
• API: サービス同士をつなぐ窓口。OpenAPIはその使い方を書く決まり
• GraphQL: RESTとは別のAPIの作り方。仕様の表し方も異なります
• エンドポイント: APIの個々の入口。OpenAPIではここを一覧で書きます

🏁 ひとことでまとめ

APIの使い方を、人も機械も同じように読める様式にそろえる約束事が OpenAPI です。