OpenAPIとは。

OpenAPIファイルは、OpenAPIドキュメントまたはOpenAPI仕様とも呼ばれ、開発者がAPIを記述できるようにします。この仕様では、利用可能なエンドポイント、運用パラメーター、認証方法、その他の情報など、このAPIの使用方法についても説明します。これらの仕様はYAMLまたはJSONで記述され、JSONスキーマはAPI内のデータ形式を記述するために使用されます。

OpenAPIは、API使用者とプロデューサーの間のドキュメンテーションだけでなく、契約（APIが何をすべきかを説明するものであり、法的拘束力はありません）としての役割を果たします。それは基本的に、標準化された形式で指示を提供する「信頼できる唯一の情報源」として機能します。

この標準化により、APIの利用と統合が簡素化されます。これにより、人間もコンピューターも、ソースコードにアクセスしたり、APIの内部の仕組みを理解したりする必要なく、特定のAPIの機能と構造を同様に理解できるようになります。また、開発者はAPIがどの言語で記述されているかに関係なく、APIを操作できるようになります。

OpenAPIは、インタラクティブな最新のドキュメンテーションを自動化し、反復的なドキュメンテーション作業を排除し、ドキュメントを最新の状態に保つのに役立ちます。OpenAPIはまた、クライアントSDK用のコード生成や、その他の定型コードを仕様書から自動的に生成することを可能にし、人為的なミスを減らし、開発者の作業負荷をさらに最小限に抑えます。

Swagger UIを含むOpenAPI仕様を使用するツールは、対話型インターフェースでAPI仕様をレンダリングできます。このインターフェースは、仕様を視覚化するだけでなく、テストおよび検証目的で、ブラウザーやWebサービスから直接実際のAPI呼び出しも可能にします。

OpenAPIは、REST APIの記述方法を標準化することで、相互運用性とツールの改善に役立ち、APIライフサイクル全体を通じてオペレーションをサポートします。強固でよく整備された仕様書は、統合、コラボレーション、エラー防止、より強力なAPI Managementをサポートし、包括的なAPI戦略を実施するための基盤ツールとなります。

仕様書の全文はGitHubに掲載されています。

事実上の業種・業務標準として、OpenAPIはAPI開発のための安全で自動化された、広く理解されているドキュメントを提供します。

OpenAPIはもともと開発者のTony Tam氏によって作成され、2011年にSwaggerという名前で初めてリリースされました。当時、API仕様は静的ドキュメントであることが多く、面倒な更新が必要で、古くなっていることもよくありました。Swaggerの仕様には、API呼び出しをライブおよびリアルタイムでテストするための「試してみる」ボタンなど、API開発におけるいくつかのイノベーションが含まれていました。

Swaggerは、ドキュメンテーションの存在に焦点を当てました。これにより、開発者は付箋のような注釈をソースコードに含めることができるようになりました。Swaggerはこれらの注釈を読み取り、ドキュメンテーションを自動的に更新できるため、面倒で反復的な更新作業を行うことなくドキュメンテーションを最新の状態に保つことができます。Swaggerはまた、APIを機械可読なJSONで記述するフォーマットを導入し、言語にとらわれないようにした。バックエンドの言語に関係なく、Swaggerは普遍的なJSONファイルをアウトプットします。

Swaggerは2015年にSmartBear Software社によって買収され、その後すぐにOpenAPIに改名され、Linux Foundation傘下の新しいOpenAPI Initiative（OAI）に寄贈されました。現在のバージョンはOpenAPI 3.1です。

OpenAPI仕様は、APIの構造と構文を定義する、人間や機械が判読できる標準化された文書です。すべてのOpenAPIドキュメントには特定のコンポーネントが含まれており、同じ基本構造に準拠していますが、一部の仕様には他の仕様よりも多くの情報が含まれています。仕様には少なくとも、フィールドとopenAPI info フィールド、および少なくとも1つのpath 、component 、またはwebhook フィールドが含まれている必要があります。¹

OpenAPI：ドキュメントで使用されているOpenAPIのバージョン（「3.1.1」など）をメモします

情報：APIのタイトルやバージョン番号、APIの説明、利用規約、連絡先情報などの一般的なAPIメタデータが含まれます。

サーバー：APIにアクセスできるベースURLのリスト（ステージング環境と本番環境の両方が含まれる場合があります）。このリストには、環境固有のホストの変数が含まれています。

パス：パスおよび関連するHTTPメソッド（または操作—例えばGET、PUT、POST）、および各パス項目のパラメーター、リクエストボディ、レスポンスを記述します。

コンポーネント：データ・スキーマ、パラメーター、レスポンス、ヘッダー、セキュリティー定義などの再利用可能なオブジェクトをリストします。これらのオブジェクトは、文書全体で参照できます。コンポーネントは、簡単に言えば$refで参照されます。このストラテジーは、API設計を可能な限り合理化します。

セキュリティー：OAuthやAPIキーなど、APIが使用するセキュリティー方式や認証メカニズムを示します。また、セキュリティー方式をグローバルに、またはオペレーション別に適用することも可能です。

タグ：オペレーションを整理するために使用されるタグの高レベルのリスト。タグを使用すると、ドキュメントの明確さが向上します（例：「ユーザー」や「注文」など）。

外部ドキュメンテーション：APIのガイド、オンボーディング・ドキュメント、その他の外部ドキュメントへのリンク

webhooks：APIが受信するインバウンド呼び出しを記述します。

OpenAPIは、API開発者と消費者に信頼できる唯一の情報源を提供し、APIプロジェクトに付加価値と効率性をもたらす機能を提供します。

OpenAPIは当初、REST APIのドキュメントに重点を置いて作成されましたが、その重点は今でもその中核を維持しています。ドキュメンテーションは標準化、インタラクティブ、リアルタイムで更新され、信頼できる唯一の情報源と契約を提供します。

Open APIドキュメントを読み取って、コードをエクスポートするためのさまざまなツールが存在します。これらのツールの1つがSwagger Codegenで、OpenAPI仕様に従って記述されたドキュメントを読み取ります。Swagger Codegenは、APIクライアント・コード、ソフトウェア開発キット（SDK）、サーバー・サイド・コード（スタブ）、および人間が読める最新のドキュメントを含むWebページを作成できます。

OpenAPIの最も革新的な機能の1つは、ブラウザーから直接リアルタイムのテストと検証を可能にする「試してみる」ボタンです。無料のオープンソース・ツールであるSwagger UIを使用すると、開発者が実際のリクエストを送信して、希望に応じて応答できるようにするための視覚的なインターフェースが可能になります。このツールにより、リクエストが機能していることを即座に簡単に検証できます。

OpenAPIは、サービスとしての統合プラットフォーム（iPaaS）で一般的に使用されます。

iPaaSプラットフォームは、ITエコシステム内のさまざまなアプリケーションを理解し、接続するためにOpenAPI仕様を使用しています。アプリケーションがAPIを記述したOpenAPI仕様を公開すると、iPaaSプラットフォームはこの情報を使ってエンドポイント、認証方法、データ構造を自動的に発見することができます。この戦略により、eコマース・プラットフォームと会計ソフトウェアの接続などの統合をより迅速に構築できるようになります。

OpenAPIを使用すると、フロントエンドとバックエンドの開発者が並行して作業できるようになります。並行作業は、場合によってはあることですが、バックエンド・チームがデータベースを稼働させるまでフロントエンド・チームが待たされるよりは望ましい状態です。OpenAPI契約により、フロントエンド・チームは実際のAPIサーバーと同じように動作するモックAPIサーバーを作成し、バックエンドの開発が完了する前にテストを可能にして最適化することができます。

APIガバナンス（組織がAPIを開発・使用する方法を指示する基準、ポリシー、プラクティス）は、APIがシームレスに一貫性があり、不必要な反復なしに動作するために不可欠です。OpenAPIは開発者間の契約として機能するため、ガバナンスとセキュリティーを最初から組み込むことができます。

例として、トラフィック・ルーティング、監視、レート制限などのタスクを処理するAPI Gatewayを考えてみましょう。API Gatewayは通常、OpenAPI仕様を使用し、仕様に記載されているトラフィック制限やその他のセキュリティー対策を適用できます。

セキュリティー・ルールについても同じことが当てはまります。OpenAPI仕様により、開発者はセキュリティー要件（OAuth 2.0やAPIキーなどの使用など）を宣言でき、これらの要件は下流（おそらくゲートウェイによって）適用できます。API契約にセキュリティー機能の概要を記載することで、開発者がサポートされていないセキュリティー方式を採用しないようにすることができます。

OpenAPIは、API接続を作成、公開、管理するスケーラブルなプロセスであるAPI Managementを、いくつかの方法で強化することができます。例えば、OpenAPI仕様は機械で読み取り可能で標準化されているため、カタログおよびポータル・ソフトウェアで自動的にインデックスを作成できます。この標準化により、組織全体でAPIの検索と理解が容易になります。この検出可能性により、チームが知らないうちに重複したAPIを構築してしまうのを防ぐことができます。

OpenAPIは、組織の基準を明確かつ強制力のあるものにすることで、一貫した管理とガバナンスも支援します。チームは、バージョン管理規則、エラー応答形式、命名パターンなどの要件を仕様内で、または仕様とともに定義できます。これらの期待事項は標準化された形式で文書化されているため、新しいAPIが追加されたときに自動的に検証できます。この検証により、手作業によるレビューへの依存が軽減され、組織のポートフォリオが拡大してもAPIの一貫性が維持されるようになります。