【おーぷんえーぴーあい】

OpenAPI とは？

最終更新: 2026年10月8日

💡 HTTP APIの構造を記述する、共通の仕様書ルール

HTTP APIのインターフェースを記述する標準仕様。パス・操作・パラメーター・リクエスト・レスポンスなどをJSONまたはYAMLで表し、対応ツールによる文書表示やコード生成に使える。

📌 このページのポイント

OpenAPI 3系の主な項目を抜粋した模式図。componentsには再利用する定義を置き、securityは認証方式の適用条件を示す。JSONでも記述でき、全項目が必須ではない。矢印は仕様書をツールへ入力して表示・生成する関係で、コードや認証処理が自動的に完成する意味ではない。

ひよこ

SwaggerとOpenAPIって同じもの？

ペンギン先生

OpenAPIはHTTP APIを記述する標準仕様で、Swaggerはその仕様を扱うUIやエディターなどのツール群だよ。もともとのSwagger仕様がOpenAPI仕様へ引き継がれたため、名前が混同されやすいんだ。

ひよこ

仕様書には何を書くの？

ペンギン先生

パス、HTTPメソッド、パラメーター、送受信するデータの構造、応答コード、認証の条件などを書くよ。たとえばGET /users/{id}がどんな応答を返すかを記述する。仕様書をJSONやYAMLで書くことと、APIのデータ形式がJSONに限られることは別なんだ。

ひよこ

コード自動生成って実際に使えるの？

ペンギン先生

OpenAPI Generatorなどで、対応する言語のクライアントコードやサーバースタブを生成できるよ。対応する仕様の版や設定はツールによる。スタブは実装の足場で、業務処理まで完成するわけではない。生成後も、実装との一致や動作を確認するんだ。

ひよこ

コードから仕様書を生成する方法もあるの？

ペンギン先生

あるよ。たとえばFastAPIはパスや型などのコード情報からOpenAPIの記述を生成する。このようなコードから始める方法と、先に仕様を書いて実装する方法がある。どちらでも、変更したときに仕様と実装が合っているか管理するんだ。

ひよこ

ほかのAPI方式でも同じ仕様書を使うの？

ペンギン先生

方式に応じた記述があるよ。GraphQLは問い合わせ可能な型やフィールドをスキーマで定義し、gRPCでは通常.protoファイルにサービスやメッセージを定義する。OpenAPIはHTTP APIのインターフェースを記述する仕様なので、何を表したいかに合わせて使い分けるんだ。

まとめ：ざっくりこれだけ覚えればOK！

「OpenAPI」って出てきたら「HTTP APIの構造を機械が読める形式で記述する標準仕様」と思えばだいたいOK！

📖 おまけ：英語の意味

「OpenAPI Specification」＝ HTTP APIのインターフェースを記述する仕様

💬 公開APIだけに限定する名前ではないよ。2015年にSmartBearがSwagger 2.0仕様を寄贈し、Linux Foundation傘下のOpenAPI Initiativeが管理する標準へ発展したんだ。

参考資料