優れたユーザーエクスペリエンスは、あらゆる製品を使用する上で重要であり、APIについても同様です。APIを利用するためのインターフェースが優れているほど、ビジネスおよび技術的な目標を達成する可能性が高くなります。
モバイルコンピューティングとクラウドコンピューティングの出現以来、APIは主流になり、ますます多くの企業や組織がAPIを作成することのビジネス価値を理解しています。多くのWebサービスが登場するにつれて、これらのサービスを採用するための明確なAPIドキュメントが必要であることが明らかになりました。
APIドキュメントは、APIを正常に利用し統合するために必要な情報です。これは、APIの利用方法をよりよく理解するための技術的な文章、コードサンプル、および例の形式で提供できます。APIコンシューマーがアプリケーションに迅速に採用できるようにするための簡潔で明確なドキュメントは、APIの採用を促進したい組織にとって、もはやオプションではありません。
ドキュメントが重要な理由
ProgrammableWebによる調査では、APIコンシューマーは、価格やAPIパフォーマンスよりも、APIの意思決定において、完全で正確なドキュメントが最大の要素であると考えていることがわかりました。
優れたドキュメントは、開発と利用を加速し、サポート電話への対応に費やされるはずのお金と時間を削減します。ドキュメントは全体的なユーザーエクスペリエンスの一部であり、APIの成長と使用の増加のための最大の要因の1つです。
APIドキュメントの課題
APIは、他の多くの製品と同様に、開発およびリリースサイクル中に急速に進化する傾向があります。開発チームとエンドコンシューマーがAPIを効率的に操作できるように、このドキュメントを維持および更新することは、困難なプロセスになります。これは、エンドコンシューマーにドキュメントを提供するために.pdfなどの静的ドキュメントを使用している場合は特にそうです。2番目の問題は、複数のWebサービス間の相互作用を促進することです。アプリケーションは、互いに継続的に通信および相互作用する複数のサービスで構成されています。
RESTfulサービスが増加するにつれて、それらを実装するために使用されるプログラミング言語も増加し、それらの通信が困難になっています。APIドキュメントは、APIを利用するためのインターフェースと考えることができ、このようなさまざまなWebサービス間の相互作用を促進する必要があります。通常のAPIインターフェース（テキストドキュメントやJavadocsなど）では、相互に通信できません。これらの課題とその他のAPIの課題により、Swagger仕様が作成されました。
次のセクションでは、OpenAPI仕様（以前はSwagger仕様として知られていました）がドキュメントの課題に対処するのにどのように役立つかを詳しく見ていきます。
APIドキュメントにOpenAPIを使用する理由
SwaggerチームがSmartBearに参加し、仕様が2015年にOpenAPIイニシアチブに寄贈された後、OpenAPI仕様（OAS）に名前が変更されたSwagger仕様は、RESTful APIを定義するための事実上の標準になりました。
（注：このリソース全体で、OpenAPIおよびOASという用語を使用します。これは、仕様を参照することを意味します。）
OASはAPIの契約を定義し、開発チームやエンドコンシューマーなど、APIのすべての関係者が、APIが何をするかを理解し、アプリケーションに統合することなく、そのさまざまなリソースを操作できるようにします。この契約は言語に依存せず、人間が読めるため、機械と人間の両方がAPIの目的を解析して理解できます。
OAS契約は、APIが何をするか、そのリクエストパラメーターとレスポンスオブジェクトを、コード実装を示すことなく記述します。OASで定義されたWebサービスは、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の契約を設計することを提唱しています。これは比較的新しいアプローチですが、特に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と統合されています。この統合により、開発者はSwaggerHubでAPIドキュメントを自動的にホストおよび可視化し、内部および外部の関係者による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 Centralで入手できる成果物のビルドとデプロイにMavenを使用します。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のコンテナServlet、または手動を使用して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のような優れたツールを使用すると、APIエンドポイントごとに重要な詳細を簡単に記述できるOAS準拠の構造が整います。生成されたファイルは、APIの技術ドキュメントおよびインタラクティブドキュメントの基礎となります。
生成されたコントラクトからのドキュメントは、エンドユーザーがAPIを成功させるために使用できる有意義で理解しやすい情報を追加することを意味します。OASを使用すると、次の重要な詳細を記述できます。
- メディアタイプ:メディアタイプは、リクエストまたはレスポンス本文データの形式です。Webサービス操作では、さまざまな形式（最も一般的なJSON、XML、画像）でデータを受け取ったり返したりできます。
- エンドポイント/リソース:これらには、ドキュメント用にオプションの短い要約と長い説明を含めることができます。この情報は、このエンドポイントのすべての操作に関連すると想定されています。説明は複数行にすることができ、リッチテキスト表現にはMarkdown (CommonMark)をサポートします。
- リクエスト本文:リクエスト本文は、通常、「作成」および「更新」操作（POST、PUT、PATCH）で使用されます。たとえば、POSTまたはPUTを使用してリソースを作成する場合、リクエスト本文には通常、作成されるリソースの表現が含まれています。
- レスポンス:API定義では、すべてのAPI操作のレスポンスを指定する必要があります。各操作には、少なくとも1つのレスポンス（通常は成功レスポンス）が定義されている必要があります。レスポンスは、そのHTTPステータスコードと、レスポンス本文やヘッダーで返されるデータによって定義されます。
- 認証:認証は、securityDefinitionsキーワードとsecurityキーワードを使用して記述されます。securityDefinitionsを使用してAPIでサポートされているすべての認証タイプを定義し、securityを使用して特定の認証タイプをAPI全体または個々の操作に適用します。
- 例： パラメータ、プロパティ、オブジェクトに例を追加すると、WebサービスのOpenAPI仕様がより明確になります。例は、APIを何らかの方法で処理するツールやライブラリで読み取ることができます。
OAS定義内で定義できる情報の種類はほんの一例です。 OASを使用したAPIのドキュメント化の詳細については、こちらをご覧ください。
ドキュメントはAPIの取扱説明書であり、APIのビジネス目標を達成するための最大の推進力の一つであることを忘れないでください。消費者に愛されるAPIドキュメントを作成するには努力が必要ですが、その投資は、優れた開発者エクスペリエンス、容易な実装、APIの採用の向上という形で大きな見返りをもたらします。
最後のセクションでは、SwaggerHubがOASを使用したAPIドキュメントのワークフローをどのようにさらに支援できるかを見ていきましょう。
SwaggerHubでのAPI設計とドキュメント
ドキュメントは、難しいプロセスになる可能性があります。これは、執筆者から多くの時間、品質、共感が求められる手動の共同作業です。APIコードからドキュメントへの道のりをたどる上で、最も重要なことは、追加のセットアップで苦労する必要のないシームレスなワークフローを持つことです。ドキュメントはユーザーと顧客がAPI製品を利用するために使用する最初のインターフェースであるため、APIドキュメントには独自の特別な配慮と対応をすることが推奨されます。
SwaggerHubは、API開発ワークフロー全体で一貫性と規律を推進するために構築された、統合されたAPI設計およびドキュメントプラットフォームです。これは、すべての作業のための専用プラットフォームであり、すべての構成とホスティングが処理されるため、ドキュメントをAPIワークフローにシームレスに統合できます。
既存のAPIコードからAPIの契約が生成されたら、SwaggerHubにインポートしてAPIの旅を続けることができます。インタラクティブなドキュメントは自動的に生成され、SwaggerHubでホストされます。定義は編集可能で、テクニカルライターはAPIに適切な情報を追加して、消費者が統合に必要な情報を得ることができます。SwaggerHubの組み込みツールは、ドキュメントプロセスをさらに支援します。
その一部を以下に示します。
- 安全なクラウドホスティング： API用に構築されたプラットフォームにAPI定義を保存します。SwaggerHubは、ドキュメント化プロセス全体を通して作業を自動保存し、サーバーを設定する必要なく、ドキュメントをホストするための中央の場所を提供します。
- 標準化とガバナンス： 消費者のエクスペリエンスを向上させるために、すべてのAPIを組織の設計標準に準拠させます。開発者がAPI全体でスタイルの整合性を維持するために参照する必要があるWikiページ、GitHubドキュメント、PDFはもう必要ありません。SwaggerHubがそれらを標準化します。
- コラボレーションと問題追跡： 一元化されたプラットフォームで複数の利害関係者と連携します。SwaggerHubは、チームが設計とドキュメント化のプロセス全体を通してコラボレーションし、フィードバックを収集し、SwaggerHubエディターでのコメントを使用してリアルタイムで問題を追跡するためのプラットフォームを提供します。
- APIゲートウェイへのデプロイ： SwaggerHubはAPI定義の信頼できる情報源として機能し、クラウドでの設計とドキュメント化作業を処理し、OAS定義をAWS、Microsoft Azure、ApigeeなどのAPIゲートウェイにシームレスにプッシュできます。
無料で始めましょう！
SwaggerツールでOASを使用すると、ドキュメントに関する懸念が軽減され、自動生成され、最小限のメンテナンスで済むインタラクティブなドキュメントを作成できます。既存のAPIセットのOpenAPI定義を生成する必要がありますか？ Swagger Inspectorをお試しください。
設計とドキュメント化のプロセスを標準化したいですか？ 今すぐSwaggerHubを始めましょう。