優れたユーザーエクスペリエンスは、あらゆる製品を利用する上で重要であり、API にも同じことが言えます。API を利用するためのインターフェースが優れていればいるほど、ビジネス上および技術上の目標を達成できる可能性が高まります。
モバイルとクラウドコンピューティングの出現以来、API は主流となり、ますます多くの企業や組織が API の作成におけるビジネス価値を理解しています。多くのウェブサービスが登場するにつれて、これらのサービスを採用するために明確な API ドキュメントが必要であることが明らかになりました。
API ドキュメントとは、API を正常に利用し、統合するために必要な情報です。これは、API の利用方法をよりよく理解するための技術文書、コードサンプル、例などの形をとることができます。API 消費者がアプリケーションに迅速に採用できるようにする簡潔で明確なドキュメントは、API の採用を推進したい組織にとって、もはやオプションではありません。
なぜドキュメントが重要なのか
ProgrammableWeb の調査によると、API 消費者は、完全で正確なドキュメントを API の意思決定において最大の要因と考えており、価格や API パフォーマンスよりも重要視しています。
良いドキュメントは開発と消費を加速させ、サポートへの電話対応に費やされる時間とお金を削減します。ドキュメントは全体的なユーザーエクスペリエンスの一部であり、API の成長と利用を促進する最大の要因の 1 つです。
API ドキュメントの課題
API は、他の多くの製品と同様に、開発およびリリースサイクル中に急速に進化する傾向があります。開発チームとエンドユーザーのためにこのドキュメントを維持および更新し、API を効率的に利用できるようにすることは、困難なプロセスになります。これは、エンドユーザーにドキュメントを提供するために .pdf のような静的ドキュメントを使用している場合に特に当てはまります。2番目の課題は、複数のウェブサービス間の相互作用を促進することです。アプリケーションは、常に相互に通信および対話する複数のサービスで構成されています。
RESTful サービスの数が増えるにつれて、それらを実装するために使用されるプログラミング言語も増え、それらの間の通信がより困難になっています。API ドキュメントは、API を利用するためのインターフェースと考えることができ、そのため、これらの異なるウェブサービス間の相互作用を促進する必要があります。テキストドキュメントや Javadocs のような通常の API インターフェースでは、相互に通信することはできません。これらの課題と、その他の API の問題点が Swagger 仕様の作成につながりました。
次のセクションでは、OpenAPI Specification (以前は Swagger Specification として知られていました) がドキュメントの課題にどのように対処できるかについて詳しく見ていきます。
API ドキュメントに OpenAPI を使用する理由
Swagger チームが SmartBear に加わり、仕様が 2015 年に OpenAPI Initiative に寄贈された後、OpenAPI Specification (OAS) に改名された Swagger Specification は、RESTful API を定義するための事実上の標準となっています。
(注: このリソース全体を通して OpenAPI および OAS という用語を使用します。これは仕様を参照することを意味します。)
OAS は API のコントラクトを定義し、開発チームであろうとエンドユーザーであろうと、API のすべての関係者が、API が何をするか、そしてさまざまなリソースとどのように対話するかを、自身のアプリケーションに統合することなく理解できるようにします。このコントラクトは言語に依存せず、人間が読める形式であり、マシンと人間の両方が API が何をするべきかを解析して理解できます。
OAS コントラクトは、コードの実装を一切示すことなく、API が何をするか、そのリクエストパラメータとレスポンスオブジェクトを記述します。OAS は言語に依存せず機械が読み取り可能であるため、OAS で定義されたウェブサービスは、構築されている言語に関係なく相互に通信できます。
OAS はドキュメント作成にどのように役立ちますか？
Swagger が最初に採用された最大の理由の 1 つは、RESTful API のドキュメント作成を効率化する能力でした。Swagger UI (オープンソースまたは SwaggerHub プラットフォーム内) のようなツールを使用すると、OAS コントラクトをインタラクティブな API コンソールに変換でき、消費者はそれを使用して API と対話したり、API がどのように動作するべきかをすばやく学習したりできます。
API のドキュメントを生成することは、OpenAPI で API を定義する利点の 1 つにすぎません。その他の利点としては、以下のようなものがあります。
- 内部チームメンバーが API を理解し、その属性について合意するのを支援する: API 定義により、Swagger UI のようなドキュメントツールが API を視覚化できます。すべての内部 API を視覚化することで、開発者は上流および下流のサービスを迅速かつ簡単に使用できます。SwaggerHub のようなチームベースのツールは、API のドキュメントに関するコラボレーションを可能にし、内部消費のためにそれらをホストします。
- 外部関係者が API とその機能について理解するのを支援する: 繰り返しになりますが、Swagger UI はドキュメント作成のためのよく使われる視覚化ツールです。内部利用だけでなく、外部採用にも利用されます。SwaggerUI にはインタラクティブ性が組み込まれているため、外部の消費者は API のすべてのリソースを試して、コードベースで使用する前に慣れることができます。SwaggerHub プラットフォームを使用すると、組織は外部の消費者に制御されたアクセスを提供することもできます。
- API のテストを作成する: OAS 定義は、誰かが API を呼び出したときに成功した応答がどのように見えるかを記述するコントラクトを提供します。このコントラクトは、API のテストに必要なセットアップチームの量を大幅に削減できるテストケースを生成するためにも再利用できます。
- 実装コードと SDK を生成する: ドキュメントの生成に加えて、OpenAPI 定義は、API の実装コードと SDK を足場とすることで開発を加速するためにも使用できます。API 定義ファイルは、Swagger Codegen や SwaggerHub などのさまざまなツールにインポートして、Java、Scala、Ruby などの多くの異なる言語でこれらのスタブコードを作成できます。
OAS と Swagger ツールを API 開発ワークフローに導入すべき理由を説明したので、次の疑問は、実際にどのように始めるかです。次のセクションでは、OAS を始めるためのさまざまなアプローチについて詳しく見ていきます。
OpenAPI へのアプローチ
OAS 定義を作成する際に、2つの重要な考え方が浮上しています。「デザインファースト」と「コードファースト」という API 開発へのアプローチです。
デザインファーストのアプローチは、コードを記述する前に API のコントラクトを設計することを提唱しています。これは比較的新しいアプローチですが、特に OpenAPI の使用により急速に普及しています。デザインファーストのアプローチでは、API コントラクトが中心的な草案として機能し、チームメンバー全員が API の目標と、API のリソースがどのように公開されるかについて足並みをそろえることができます。
コードを書く前に設計上の問題を発見することは、実装がすでに完了した後に行うよりも、はるかに効率的で合理的なアプローチです。
チームがデザインファーストのアプローチに移行する準備ができている場合は、まず API 定義の作成に慣れる必要があります。プロセスを開始するのに役立つリソースをいくつか紹介します。
「コードファースト」アプローチ
コードファーストアプローチ（「ボトムアップ」アプローチとしても一般的に知られています）は、API 構築におけるより伝統的なアプローチであり、ビジネス要件が設定された後にコード開発が行われ、その後、コードから API のドキュメントが作成されます。
多くの API チームにとって、OpenAPI を始めるということは、「コードファースト」アプローチから始めて、既存の API セットから定義を生成することを意味します。既存の API を持っている場合に OAS 定義を生成するための、他のいくつかの人気のある方法を見てみましょう。
Inspector を使用して OAS 定義を生成する
Swagger Inspector は、API リクエストを迅速に実行し、そのレスポンスを検証し、対応する OpenAPI 定義を生成するための使いやすい開発者ツールです。Swagger Inspector を使用すると、各エンドポイントを呼び出し、関連するレスポンスを使用して OAS 準拠のドキュメントを生成するか、一連の呼び出しを連結して複数の API エンドポイントの完全な OAS ドキュメントを生成することにより、既存の REST API の OAS ベースのドキュメントを迅速に生成できます。
Swagger Inspector を使って、ブラウザウィンドウから直接、素早く API コールを実行できます。最初のコールを実行した後、無料アカウントを作成し、Inspector 内にコール履歴を保存できます。
Swagger Inspector を使用すると、呼び出したすべてのエンドポイントの OpenAPI ファイルを自動的に生成でき、貴重な開発時間を節約し、テクニカルライターが優れたドキュメントの作成に取り掛かることができます。
Swagger Inspector は、チーム向けの API 設計およびドキュメント作成プラットフォームである SwaggerHub と統合されています。この統合により、開発者は API ドキュメントを SwaggerHub で自動的にホストおよび視覚化でき、内部および外部の関係者による API の発見と利用を可能にします。
既存の API から OpenAPI を生成する方法
Swagger Inspector にアクセスし、ドキュメントを作成したいリソースのエンドポイントを挿入します。その後、Swagger Inspector の履歴セクションから右側のパネルに移動し、「API 定義を作成」をクリックして OAS 定義を作成できます。
Inspector の優れた点は、複数のエンドポイントを選択し、それらのドキュメントをコレクションを通じて単一の OpenAPI ファイルに統合できることです。
生成された OpenAPI ファイルを SwaggerHub でホストしたり、Swagger Inspector で呼び出し履歴を保存したりするには、SwaggerHub アカウントが必要です。
すでに SwaggerHub アカウントをお持ちの場合は、その認証情報で Swagger Inspector にログインできます。Swagger Inspector アカウントを作成すると、自動的に SwaggerHub ファミリーに加わります。アカウント作成後は、いつでもどこでもすべてのテスト履歴に簡単にアクセスでき、Inspector のボタンをクリックするだけで対応する OpenAPI 仕様を生成できます。
生成された定義は、チームが API ドキュメントを構築するための OAS 準拠の構造を提供します。定義が整ったら、サポートされるコンテンツタイプ、説明、例、認証タイプなどの重要な詳細を追加できます。
このリソースの後半で API ドキュメントを構築し続ける方法について詳しく説明しますが、まず、OAS 定義を生成するための他のいくつかの人気のある方法を探ってみましょう。
実行時における OAS 生成
Swagger-core は、Swagger の Java 実装です。現在のバージョンは JAX-RS とプレーンなサーブレットをサポートしています。
この方法では、Swagger/OAS コントラクトは、さまざまなリソース、メソッド、およびコントローラーに追加されたメタデータに基づいて API から生成されます。このメタデータは、実行時にコントラクト、クライアントサイドコード、およびその他の成果物を生成します。通常、このメタデータはコードアノテーションの形式になります。ツールは、さまざまなメソッドと関数がリソースに対して呼び出されるとトリガーされ、API で定義されたメタデータから OAS コントラクトを生成します。
このプロセスをより詳細に説明するために、Jersey フレームワークを使用して JAX-RS でコーディングされた API から OpenAPI 仕様を生成する必要があるケースを考えてみましょう。
既存の API から OAS ドキュメントを生成するには、次の 3 つのステップが必要です。
- アプリケーションに依存関係を追加する
- Swagger Core をアプリケーションに接続する
- OAS コントラクトを初期化する
Swagger プロジェクトは、成果物のビルドとデプロイに Maven を使用しており、Maven Central で利用可能です。Swagger Core を実行するには、これらの Maven の依存関係を JAX-RS でコーディングされた API に追加する必要があります。
典型的な Maven の依存関係は次のようになります。
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jersey-jaxrs</artifactId>
<version>1.5.12</version>
</dependency>
Jersey REST フレームワークの主要バージョンの違いにより、Jersey 2.x のユーザーは swagger-jersey2-jaxrs 依存関係を使用する必要があります。次のステップは、Swagger Core を API にフックすることです。Web サービスで Jersey が設定されている方法に応じて、Spring、Jersey のコンテナサーブレット、または手動で Swagger Core をアプリケーションにフックできます。
最後に、前のステップで追加されたコードアノテーションに基づいて、実行時にアプリケーション内で OAS 定義を初期化できます。生成された OAS 定義は、JSON と YAML でそれぞれ定義された 2 つのファイルになります。
このプロセスをよりよく理解するための追加リソースをいくつか紹介します。
- Jersey プロジェクト用の Swagger の生成
- Spring ベース API 用の Swagger の生成
- PHP ベース API 用の Swagger の生成
ビルド時における Swagger 生成
この方法では、OAS コントラクトは API の前処理時、つまり実行時前に生成されます。API 内のさまざまなリソース、メソッド、および関数に対するコメントは、OAS 定義の生成に役立ちます。これらのコメントは通常、コントラクトの生成に使用するツールの種類に基づいた、事前定義された特殊な構文で記述されます。ツールはこれらの特殊なコメントについて API コードをスキャンし、OAS コントラクトを出力として生成します。Cakephp-swagger および grape-swagger は、ビルド時に OAS コントラクトを生成するツールの主要な例です。
どのメソッドにも長所と短所があります。使いやすさと速度という点では、Swagger Inspector が他のツールを凌駕します。5 回以下のクリックで、ユーザーは SwaggerHub でホストされている既存の API から完全に構造化された OAS 定義を得ることができます。
Swagger Inspector は最終的なドキュメントの基盤のみを生成するため、ライターはリソース、メソッド、および消費者がそれらを使用する方法を正確に詳細に記述するために時間を費やす必要があります。実行時に OAS 仕様を生成すると、追加の依存関係、開発時間という形でソフトウェアの負荷がかかり、システムにオーバーヘッドが追加される可能性があるというコストがかかりますが、コードからより正確な API コントラクトが生成されます。
逆に、API の実行時前に OAS コントラクトを生成する方が軽量なプロセスですが、手動で維持する必要があるため、生成された OAS コントラクトが API の機能を正確に記述していない可能性があります。どちらのアプローチでも、生成された OAS ファイルが API の操作を正確に表すことを保証するために、追加の作業が必要になる場合があります。
OAS 定義からの API のドキュメント化
OAS 定義を生成するためにどのアプローチを採用するにしても、API ドキュメントを構築するには、まだかなりの追加作業が必要です。
Swagger Inspector や Swagger Core のような優れたツールを使用すると、OAS 準拠の構造が用意され、API エンドポイントごとに重要な詳細を簡単に入力できます。生成されたファイルは、API の技術的およびインタラクティブなドキュメントの基礎となります。
生成されたコントラクトからのドキュメント作成とは、エンドユーザーが API を成功させるために使用できる、意味があり、理解しやすい情報を追加することを意味します。OAS を使用すると、次のような重要な詳細を記述できます。
- メディアタイプ: メディアタイプは、リクエストまたはレスポンスの本文データの形式です。ウェブサービス操作は、異なる形式でデータを受け入れ、返すことができ、最も一般的なものは JSON、XML、および画像です。
- エンドポイント/リソース: これらには、ドキュメント作成のためにオプションの短い要約と長い説明を含めることができます。この情報は、このエンドポイントのすべての操作に関連している必要があります。説明は複数行にわたることができ、リッチテキスト表現のために Markdown (CommonMark) をサポートしています。
- リクエストボディ: リクエストボディは通常、「作成」および「更新」操作（POST、PUT、PATCH）で使用されます。たとえば、POST または PUT を使用してリソースを作成する場合、リクエストボディには通常、作成されるリソースの表現が含まれます。
- レスポンス: API 定義は、すべての API 操作のレスポンスを指定する必要があります。各操作は、少なくとも1つのレスポンスが定義されている必要があり、通常は成功レスポンスです。レスポンスは、その HTTP ステータスコードと、レスポンスボディおよび/またはヘッダーで返されるデータによって定義されます。
- 認証: 認証は securityDefinitions と security キーワードを使用して記述されます。securityDefinitions を使用して API でサポートされるすべての認証タイプを定義し、security を使用して特定の認証タイプを API 全体または個々の操作に適用します。
- 例: パラメータ、プロパティ、オブジェクトに例を追加することで、ウェブサービスの OpenAPI 仕様をより明確にできます。例は、API を何らかの方法で処理するツールやライブラリによって読み取ることができます。
これらは、OAS 定義内で定義できる情報タイプのほんの一例です。OAS を使用した API ドキュメントの作成の詳細はこちらで学べます。
ドキュメントは API の利用マニュアルであり、API のビジネス目標達成における最大の推進要因の 1 つであることを忘れないでください。消費者に愛される API ドキュメントを作成するには努力が必要ですが、その投資は、優れた開発者エクスペリエンス、より簡単な実装、そして API の採用促進という形で大きな成果をもたらすでしょう。
最後のセクションでは、SwaggerHub が OAS を使用して API ドキュメントワークフローをさらに促進する方法について見ていきます。
SwaggerHub における API 設計とドキュメント化
ドキュメント作成は厄介なプロセスになる可能性があります。それは手動で共同で行われる作業であり、執筆者には多くの時間、品質、共感が求められます。API コードからドキュメントへの道のりをたどる際に最も重要なことは、追加のセットアップで苦労することのないシームレスなワークフローを持つことです。ドキュメントはユーザーや顧客が API の提供物を利用する最初のインターフェースであるため、API ドキュメントには独自の特別な注意と扱いを与えることが通常推奨されます。
SwaggerHubは、API開発ワークフロー全体で一貫性と規律を推進するためにチーム向けに構築された、統合されたAPI設計およびドキュメントプラットフォームです。すべての設定とホスティングが処理され、ドキュメントをAPIワークフローにシームレスに統合できる、すべての作業専用のプラットフォームです。
API のコントラクトが既存の API コードから生成されたら、それを SwaggerHub にインポートして、API の旅を続けることができます。インタラクティブなドキュメントは自動的に生成され、SwaggerHub でホストされます。定義は編集可能であり、テクニカルライターが API に適切な情報を追加することで、消費者が API と統合するために必要な情報を提供できます。SwaggerHub に組み込まれたツールは、ドキュメント作成プロセスをさらに支援します。
そのいくつかには以下が含まれます。
- セキュアなクラウドホスティング: API 用に構築されたプラットフォームに API 定義を保存します。SwaggerHub は、ドキュメント作成プロセス全体で作業を自動保存し、サーバーをセットアップすることなく、ドキュメントをホストするための一元的な場所を提供します。
- 標準化とガバナンス: すべての API を組織の設計標準に準拠させ、消費者のエクスペリエンスを向上させます。SwaggerHub が API を標準化するため、開発者が API 全体のスタイルの一貫性を維持するために参照する必要のある Wiki ページ、GitHub ドキュメント、PDF はもう必要ありません。
- 共同作業と課題追跡: 一元化されたプラットフォームで複数の関係者と共同作業を行います。SwaggerHub は、チームが設計およびドキュメント作成プロセス全体で共同作業を行い、フィードバックを収集し、SwaggerHub エディターでのコメントでリアルタイムに課題を追跡するためのプラットフォームを提供します。
- API ゲートウェイへの展開: SwaggerHub は API 定義の信頼できる情報源として機能し、設計およびドキュメント作業をクラウドで処理し、OAS 定義を AWS、Microsoft Azure、Apigee などの API ゲートウェイにシームレスにプッシュできます。
無料で始めましょう！
OAS を Swagger ツールと連携して使用することで、ドキュメントに関する懸念が軽減され、自動生成され最小限のメンテナンスで済むインタラクティブなドキュメントが作成されます。既存の API セットに対して OpenAPI 定義を生成する必要がありますか？Swagger Inspector をお試しください。
設計およびドキュメント作成プロセスを標準化したいですか？今すぐ SwaggerHub を始めましょう。