OpenAPI vs GraphQL Schema: どちらのコントラクトか?
OpenAPIはRESTのエンドポイントを別ドキュメントで記述します。GraphQL schemaはGraphQL APIを定義する、組み込みかつ必須の型システムです。
OpenAPIはREST APIの任意かつ外部の記述であり - path、メソッド、パラメータ、レスポンスの形 - ドキュメント、codegen、検証を駆動します。GraphQL schemaはAPI自体に内在します。すべての型、query、mutationを定義し、runtimeでintrospectionできます。OpenAPIは本来は規約ベースのREST APIをドキュメント化しますが、GraphQL schemaは構造上APIコントラクトそのものです。
| OpenAPI | GraphQL Schema | |
|---|---|---|
| 関係 | 外部の記述 | APIに組み込み |
| 任意か? | はい(RESTはなしでも動作) | いいえ(必須) |
| introspection | ドキュメント経由 | runtimeのintrospection |
| 駆動対象 | ドキュメント、codegen、モック | 型、検証、codegen |
| 最適な用途 | RESTの記述 | GraphQLの定義 |
それぞれのコントラクトの定義方法
RESTでは、本来は緩く型付けされたAPIを形式化するためにOpenAPIを書くことを選択し、実装との同期を保つ必要があります。GraphQLではschemaが実装のコントラクトであり、クライアントは直接それをintrospectionできます。どちらも強い型付けとcodegenを可能にしますが、一方は後付けで、もう一方は本来的なものです。
CIでは
OpenAPIのpipelineはスペックをlintし、実装と一致するかをチェックします。GraphQLのpipelineはschemaを検証し、破壊的変更を防ぎます。どちらもmanaged runner上で動作し、より高速なrunnerは検証とcodegenのステップを短縮します。
結論
REST API向けのドキュメント化とツール生成: OpenAPI。構造上、強く型付けされたintrospection可能なAPIコントラクトの定義: GraphQL schema。より深い要点は、GraphQLはコントラクトを組み込むのに対し、RESTはOpenAPIを併せて保守する必要があるという点です。