【ITニュース解説】How OpenAPI Undermines a Good Developer Experience

OpenAPIは、ウェブサービスのAPI（アプリケーションプログラミングインターフェース）の仕様を記述するための、広く使われている標準的な方法である。APIは異なるソフトウェア同士が連携するための窓口のようなもので、OpenAPIはその窓口の設計図を人間にも機械にも理解できる形で定義する。しかし、このOpenAPIが、開発者がAPIを扱う際の「開発者体験（Developer Experience、略してDX）」を損ねているという指摘がある。開発者体験とは、開発者がソフトウェアやツールを使う際に感じる使いやすさや効率性のことである。特にJavaScriptやTypeScriptのような環境で、OpenAPIとは異なるアプローチをとるtRPCやoRPCといったツールが注目を集めているのは、OpenAPIの「スキーマファースト」という考え方からの脱却を求める声が高まっている証拠だと言える。

スキーマファーストとは、まずAPIの設計図（スキーマ）を先に定義し、その設計図に基づいてサーバー側のAPI実装と、クライアント側のAPI利用コードを生成するというアプローチである。理論上は、設計図があれば自動的にコードが作られ、開発効率が向上するはずだが、実際には多くの問題が発生している。この記事は、OpenAPIの複雑さが、自動でコードを生成するツール（コードジェネレーター）の信頼性を著しく低下させていると主張している。筆者は、既存のOpenAPIコードジェネレーターはどれも完全ではなく、その原因はOpenAPIの仕様自体にあると指摘している。

OpenAPIの仕様が複雑である理由の一つは、エラーハンドリングの難しさにある。APIを使った通信では、ネットワークエラー、サーバー側の問題を示す5xxエラー、クライアント側の問題を示す4xxエラーなど、さまざまな種類のエラーが発生する。これらのエラーは、例えば「404 Not Found」のように何もデータが返されないケースもあれば、「429 Too Many Requests」のように再試行に関する情報が返されるケース、あるいは「400 Bad Request」のように予測不能な形式でエラーの詳細が返されるケースなど、状況に応じて返されるデータの形式や内容が大きく異なる。コードジェネレーターは、これらの多様なエラーケースを自動的に判別し、適切に処理するためのコードを生成することが非常に困難なのだ。結果として、開発者はこれらの複雑なエラー処理ロジックを一つ一つ手作業で実装しなければならず、大きな負担となっている。

また、データの形式をどのように扱うか（シリアライゼーション）にも問題がある。OpenAPIでは、同じデータをAPIのエンドポイントに送信する際でも、テキスト形式で送信する方法が複数存在する。これらは多くの場合、過去の互換性のために残されているものであり、実際には同じ結果をもたらす。このような冗長性は、開発者にとってどちらを選べばよいのか迷いを生み、混乱の原因となる。

さらに、データ構造を定義するためのJSON Schemaにも特殊なケースが多く存在する。例えば、複数のスキーマを組み合わせる「allOf」という機能を使う際、特定のフィールドを必須とするために空のオブジェクトと組み合わせるような記述方法がある。この場合、コードジェネレーターは、参照されている全てのオブジェクトのフィールドをたどり、その中で空のオブジェクトによって必須とされているフィールドだけを抽出して処理しなければならない。これは非常に複雑な処理であり、現在の多くのジェネレーターはこの特殊なケースを正しく扱えていないという。

APIのレスポンスのステータスコードを定義する際、「4XX」（400番台の全てのエラー）や「5XX」（500番台の全てのエラー）といった範囲指定、あるいは「default」（それ以外の全てのエラー）といった汎用的な指定が可能である。これらのワイルドカード的な指定は柔軟性をもたらすが、コードジェネレーターにとっては、具体的なステータスコードごとの詳細な定義とどのように組み合わせるかを判断するのが非常に難しく、開発者体験を損ねる原因となっている。

これらの複雑な要件や特殊なケースが絡み合うため、現状ではOpenAPIの仕様全てを正確に処理できるコードジェネレーターは存在しない。TypeScriptを利用する開発者は、「まあまあ動く」程度の不完全なツールを使って開発を進めているのが実情であり、OpenAPIの本来の目的である「自動コード生成」が本質的にうまく機能していないという問題が浮上している。

筆者は、Cap'n Webプロトコルのような統一されたアプローチが、OpenAPIでは考えられないような良い開発者体験を提供していることに触れ、OpenAPIが解決しようとしている問題の中には、そもそも存在すべきではない問題が含まれていると指摘する。OpenAPIのスキーマファーストアプローチは、本質的に開発者体験を低下させる運命にあるという厳しい意見も述べている。実際、MicrosoftがOpenAPI仕様を生成するためだけに独自のDSL（ドメイン固有言語）を実装したことや、OpenAPIのコードジェネレーターを提供することが主要なビジネスとなっている企業が存在すること自体が、この問題の根深さを示している。

したがって、特に新しいプロジェクトや内部サービスを開発する際には、OpenAPIのようなスキーマファーストのアプローチよりも、tRPCのようなモダンなRPCプロトコルや、ソースコードからAPI仕様を自動生成する「コードファースト」のアプローチなど、より開発者体験に優れた代替手段を検討すべきだと筆者は提言している。開発の現場では、OpenAPIの限界を理解し、プロジェクトの特性に応じて最適なAPI設計・開発手法を選択することが重要である。