OpenAPI仕様

OpenAPI仕様とは、RESTful APIの設計・文書化を標準化したマシンリーダブルなフォーマットである。

概要

OpenAPI仕様は、もともとSwaggerとして開発されたAPI記述言語を基盤に、Linux Foundation が主導する OpenAPI Initiative によって正式に標準化された。JSON もしくは YAML 形式で API のエンドポイント、リクエスト・レスポンスの構造、認証方式などを一元的に定義できる点が特徴である。金融業界では、PSD2 やオープンバンキング規制に伴い、銀行が第三者サービスプロバイダー（TPP）へ安全かつ透明性の高いデータアクセスを提供するための契約書として採用されるケースが増えている。特に、API 銀行・BaaS プラットフォームは、OpenAPI 仕様書を公開し、開発者が SDK を自動生成したり、テスト環境を即座に構築できるよう支援している。

役割と機能

OpenAPI 仕様は API の「設計図」として機能する。具体的には以下の場面で活用される。
1. ドキュメント生成：Swagger UI、ReDoc 等のツールにより、人間が読めるインタラクティブな API ドキュメントを自動作成できる。
2. コードスケルトン生成：多言語 SDK やサーバー・クライアントスタブを自動生成し、開発コストを削減する。
3. 契約テスト：OpenAPI 仕様書と実際の API 実装が一致しているかを検証する Contract Testing フレームワークに組み込まれる。
4. セキュリティ定義：OAuth2、OpenID Connect、HMAC 等の認可・認証スキーマを仕様内で明示できるため、PSD2 の「安全なデータ共有」要件を満たす設計が容易になる。
5. 相互運用性確保：金融機関と TPP との間で共通の API 定義を使用することで、エンドポイントやパラメータの解釈差異を排除し、統合プロセスをスムーズにする。

特徴

• マシンリーダブル：JSON/YAML による構造化データは自動解析が可能であり、CI/CD パイプラインへ組み込みやすい。
• 言語・プラットフォーム非依存：仕様書だけで多様な開発環境に対応できるため、金融機関の既存システムと新規サービスを横断的に結びつける際に有効。
• バージョニングサポート：API の進化に伴い、仕様書自体でバージョン管理が行える。これにより、旧バージョンの TPP との互換性を保ちつつ、新機能を追加できる。
• 拡張性：カスタムフィールドやサンプルデータ、例外レスポンスなどを自由に追加でき、業界固有の要件（AML・KYC、トークナイゼーション等）を仕様書内で表現可能。
• エコシステム統合：OpenAPI 仕様は SwaggerHub、Apigee、AWS API Gateway 等多くのプラットフォームとネイティブに連携できるため、金融機関が選択するインフラストラクチャーに合わせて柔軟に展開できる。

現在の位置づけ

近年、オープンバンキングや API 銀行の普及に伴い、OpenAPI 仕様は「デジタル金融サービスの共通インタフェース」として不可欠な要素となっている。PSD2 の実施後、多くの EU 機関が OpenAPI を用いた API 定義を推奨し、規制遵守の一環として必須化しているケースも増加。
BaaS プラットフォームでは、OpenAPI 仕様書をベースに SDK やデータモデルを提供し、eウォレットや QR コード決済、トークナイゼーションサービスへの統合を簡易化している。さらに、PCI DSS のようなセキュリティ規格と組み合わせることで、カード情報の安全な取り扱いも保証できる。
将来的には OpenAPI 仕様のバージョン 3.1 で導入されるハイパーメディアやサーバー変数機能が、金融 API の柔軟性と拡張性をさらに高めると期待されている。これにより、リアルタイム決済やチャージバック処理などの複雑なビジネスロジックも、標準化された仕様書で表現できるようになる見込みだ。