OpenAPI vs Swagger：徹底解説

OpenAPI とその作成のタイムライン

OpenAPI は、世界的に認められている RESTful アプリ設計仕様です。Google、Capital One、SmartBear、Microsoft、Apigee、PayPal などの大手企業が OpenAPI Initiative の下でこの取り組みを開始しました。Linux Foundation もこの仕様を推奨しています。

OpenAPI は、ベンダーや言語に依存しない RESTful アプリのインターフェースとしても知られています。ドキュメントやソースコードの断片、ネットワーク混雑の監査に頼ることなく、人と機械が連携できる手段として広く利用されています。

作成のタイムライン

• (2009) - エンジニアの Tony Tam によって、OpenAPI と Swagger が生み出されました。当初、企業向けにオープンソースの Swagger 仕様が発表されました。
• (2011) - Swagger UI のバージョン1は Wordnik の JSON アプリを記述でき、企業の開発者向けコンソールやドキュメント、コード連携、コード生成の機能を活用しました。
• (2012) - 改良された（ただしベータ版の）バージョンが登場しました。
• (2014) - 初の公式な Swagger Spec 2.0 が公開され、API利用者から高い評価を受けました。
• (2015) - SmartBear が Swagger Spec を引き継ぎました。
• (2016) - Swagger は『OpenAPI Specification』に名称変更され、別の Git リポジトリへ移行されました。
• (2017) - 現在は OpenAPI Initiative に含まれています。

現在、バージョン 3.1.0 が公開され、最高の仕様とされています。API の書式や構造作りに大きな効果を発揮し、HTTP 認証スキームに準じた認証・認可が可能となりました。

さらに、ヘッダーやクッキーに API キーを送ることで、ユーザーの認証や認可が実現できます。OAuth 2 や OpenID Connect Discovery 方式も v3.1.0 から利用可能です。

Swagger、その歴史とツールキット

Swagger は、RESTful アプリの利用方法を分かりやすく定義するためのインターフェース記述言語で、JSON を用います。

Swagger ツールキットはオープンソースおよび商用レベルのツールを複数備えており、通常の API ライフサイクルで利用されます。簡潔に言えば、Swagger ツールキットは API 作成を簡素化します。2017 年には Swagger ツールが 1 日で 10 万回以上ダウンロードされた事実が、その普及度を物語っています。

次のようなツールが含まれています：

1. ‍Swagger Core は、Java ライブラリ群で、OpenAPI 定義の作成、利用、展開に使用されます。
2. エンドユーザーは Swagger Editor を使い、ウェブブラウザ上で YAML 形式の OpenAPI 仕様を作成・修正できます。これにより、ドキュメントの読みやすさの向上や、エンドユーザー視点でのプレビュー、正確性や使いやすさの改善が図れます。
3. Swagger UI リポジトリ内の HTML、JS、CSS ページにより、ドキュメント作成が容易になります。
4. デザインとドキュメント作成ツールとしては、SwaggerHub が適しており、プロフェッショナルも多様な OpenAPI プロジェクトで利用しています。
5. ‍Swagger Parser は、仕様の解析を支援します。
6. ‍Swagger Codegen は、API サーバスタブ、SDK などのドキュメント生成に利用されるツールです。
7. OpenAPI 定義作成プロセスの検証は Swagger Inspector により行えます。その厳格なテスト機能によってプロセスの改善が図られます。

Swagger と OpenAPI：主な4つの違い

• ‍a. 両者の基本から始めます:
  

OpenAPI = RESTful アプリを適切に定義・説明するための仕様;

Swagger = API 仕様の導入を簡便にするためのツールキット。

• Swagger は 1 つのサーバーにつきホスト＋ベースパスの組み合わせを許容します。一方、OpenAPI は複数のサーバー URL やサブドメインパスを追加でき、柔軟性に優れています。
• Swagger ツールキットの全ツールは OpenAPI を利用しており、その逆は必ずしも当てはまりません。
• 名称変更後も、Swagger ツールは従来の名前を維持しています。

API作成者や業界への Swagger と OpenAPI の全体的な影響

Tony Tam が Swagger 仕様を作成した際、API セキュリティや業界全体が大きく変わるとは思いませんでした。時を経て、RESTful アプリに関しては OpenAPI 仕様と Swagger が広く認識されるようになりました。

OpenAPI はオープンソースで無料の機能として提供されるため、初心者の開発者が経験を積み、可能性を発揮する場となっています。新米開発者は広いフィールドで API 開発の腕を磨けます。

API 開発の各段階でセキュリティ基準を維持することが最優先されていましたが、近年 API 脆弱性は増加傾向にあります。Cisco Systems、Facebook、Shopify などの大企業も API の脆弱性に直面し、セキュリティ体制の強化に努めています。Equifax の API 脆弱性事故で 7 億ドルの訴訟費用が発生したことからも、企業は API セキュリティへの意識を高める必要があります。

OpenAPI の利用は、開発チームが共通の言語で容易にコミュニケーションできるようになったため、API 開発に大きな前向き効果をもたらしました。開発者が API の意図をコードや挙動から推測する手間が省けます。

また、シンプルな形で情報を伝える API は、事前に定められたセキュリティ基準の採用や、潜在的なギャップとリスクの検知を容易にします。

‍

Swagger と OpenAPI の現状

OpenAPI と Swagger は、現在 API 業界を牽引しています。これにより、API のサーバースタブ生成が簡単になり、開発者は 40 以上の言語でクライアントアプリライブラリを作成することが可能です。これが API 開発を促進し、セキュリティ強化に寄与しています。

• インタラクティブな API 作成

開発者は OpenAPI を用いてインタラクティブなドキュメントを作成できます。ドキュメント作成中に、ブラウザ上から直接 API のテストも実行可能です。

• コード生成ツールへの対応

OpenAPI は、サーバ SDK やクライアント CDK を複数の言語で作成できる点で大きな利点となります。コード生成ツールとの連携も優れています。

• 監査

OpenAPI 仕様は、API のデータ操作を守るための Contract Audit ツールと相性が良く、高度なセキュリティ対策にも寄与します。両者を組み合わせることで、作成した API のセキュリティ問題の検出や監査が手間なく実施できます。

初期段階から API 監査を行えば、開発後半に大量の API 監査に追われることを防げます。

また、API 開発の各段階で適切なセキュリティ対策が実施されることを保証します。

Swagger の今後の方向性

OpenAPI は重要なツールとして市場専門家からも高い評価を受けていますが、一部では Swagger が主要な仕様を OpenAPI に譲渡したため輝きを失っているとの見方もあります。しかし、Swagger は現在も活発に利用され、特に API テストやセキュリティ強化において重要な役割を果たしているため、その評価は再考に値するでしょう。

Swagger ツールはコードの全体像を明確に示し、コード断片の即時テストを可能にします。Swagger UI により、開発者はコマンド実行とシステム機能の詳細な把握が容易となりました。

また、OpenAPI と連動したグローバルな API 生成規格により、API 作成の標準化も実現されます。

ゼロからの API 作成も Swagger ツールを用いれば簡単です。Swagger Editor で API を即時にテストし、OAS Open API Specification に基づく設計の実用性や実際の見た目を確認できます。さらに、このツールはどこからでも利用可能です。

続いて、Swagger Inspector は独自の API 仕様生成を可能とする重要なツールです。カスタマイズした API の生成だけでなく、それらを他のチームメンバーと共有することもできます。

ウェブ上の API セキュリティについては、Swashbuckle が解決策となります。オープンソースの Swagger 実装により、エンドユーザーはすべての API のリビングドキュメントを生成でき、現行の API バージョンと同期を保ちながら、セキュリティリスクを一切残しません。

‍

結論

OpenAPI は Swagger から派生したため、混同しやすいのは当然です。

前者は RESTful アプリ作成のために設計され、機械が読み取る形式で仕様を保持するため、セキュリティ面でも優れたツールです。一方、後者はベンダーに依存しない OpenAPI 仕様の導入において、開発者のお気に入りとなっています。

今後、これら二つの用語を耳にした際に混乱せず、正しい理解に繋がることを願っています。どちらも API 分野に独自の影響を与え、API 開発を推進しています。