OpenAPIの意味

OpenAPIは、HTTP APIのインターフェースを人間とコンピューターが理解できるよう記述する標準仕様です。OpenAPI Initiativeの仕様では、ソースコードや実際の通信を調べなくてもサービスの能力を発見・理解できる、言語に依存しないインターフェースを定義します。OpenAPIドキュメントはJSONまたはYAMLで表現でき、パス、HTTPメソッド、パラメータ、リクエストとレスポンスのスキーマ、認証、エラーなどを記述します。これを利用して、APIドキュメント、クライアントやサーバーのコード、テスト用の入力などを生成できます。ただし、仕様書が存在することだけで、実際のAPI実装が仕様どおりであることや、認証・権限・データの安全性が保証されるわけではありません。OpenAPIはREST APIと一緒に使われることが多いものの、OpenAPIの文書がAPIの実装方式をすべて決めるわけではありません。仕様のバージョン、ドキュメントと実装の差分、機密情報の公開範囲、生成ツールの対応状況を確認します。旧称のSwaggerと関連しますが、現在のOpenAPI Specificationとの関係を分けて記録します。

OpenAPIが使われる背景には、HTTP APIの入力・出力・認証などを、実装を読まずに人とツールが共有できる契約として記述する必要があります。OpenAPI Initiativeの標準仕様に沿って、API実装とは分けます。

OpenAPIはHTTP APIのインターフェースを記述する仕様なので、API実装やRESTそのものとは区別して契約を確認します。

OpenAPIは、HTTP APIのエンドポイント、入力、出力、認証などを、言語に依存しない形式で記述する標準仕様です。人間向けのドキュメント生成、クライアントやサーバーのコード生成、テストなどに利用できます。APIそのものや実装フレームワークではありません。 OpenAPI Initiativeの現行仕様で、HTTP APIの言語非依存なインターフェース記述と利用目的を確認。OpenAPIをAPI実装やRESTそのものと同義にしない。