OpenAPI (Swagger) のような記述形式や、Swagger UI のようなオープンソースの実装は、API チームのAPI ドキュメントに対する考え方を変化させました。API の操作を人間と機械の両方が読み取り可能な形式で定義し、それらの操作を視覚化してエンドユーザーが API の異なるエンドポイントと対話できるようにすることで、これらのツールは API ドキュメントを手動で維持する必要性をなくしました。
これは API チームにとって明白なメリットをもたらしました。
API の正確で最新のドキュメントを維持することは、常に面倒なプロセスでした。API の「使用マニュアル」を作成するためにテクニカルライターを雇う贅沢があった組織やチームでさえ、新しい API バージョンでドキュメントを更新する際に問題に直面していました。もう1つの主要なメリットは、記述形式とそれらをサポートするツールが API ドキュメントの生成に役立つ速さです。Swagger UI はその最良の例であり、ユーザーは基本的なAPI デザインから API ドキュメントを自動的に生成でき、何時間もの時間と開発者リソースを節約できます。
ここ数ヶ月間、SwaggerHub チームは IBM Interconnect、Microsoft Build、DockerCon 2017 などのイベントに参加し、開発者、テクニカルライター、API デザイナー、DevOps、その他のソフトウェア専門家から、Swagger UI が有用な API ドキュメントの生成にいかに効率的であるかについて繰り返し聞きました。しかし、これらの会話から学んだ教訓の1つは、API エコノミーの競争の激しいエコシステムでは、API 利用者が API ドキュメントにさらに多くのことを期待しているということです。
結局のところ、RESTful API のインターフェースを生成することは、エンドユーザーにドキュメントを提供する上での良い第一歩ですが、人々が API を効果的に操作する方法を理解できるようにするためにできることのほんの始まりに過ぎません。
API ドキュメントに不足しているもの
エンドユーザーが API と連携するための UI を生成することは、優れた API 開発者エクスペリエンスを提供するための重要な第一歩です。しかし、API がビジネスと戦略的成長の中心的な役割を果たす今日のモダンな API エコノミーでは、ドキュメントは基本的な UI を超える必要があります。
この UI を生成する目的は、エンドユーザーが API の操作方法を簡単に理解するために使用できる視覚的なリソースを提供することです。これは API を操作するための使用マニュアルであり、この使用マニュアルが不完全でユーザーの役に立たない場合、ユーザーの開発者エクスペリエンスを直接損ない、API プログラムの成功を妨げる可能性があります。したがって、最終的に API を利用する際に優れた開発者エクスペリエンスを生み出すために、基本的な Swagger UI と API ドキュメントを改善する方法を考え始めることが重要です。
API ドキュメントに不足している可能性のある主要なセクションをいくつかご紹介します。
1. 概要セクション
API の基本的な UI を単に生成している場合、ドキュメントには、人々が API の機能と、そもそもなぜそれを使用したいのかを簡単に理解するための役立つ説明が欠けている可能性が高いです。API の価値を理解するために必要な情報と、始めるのに役立つ導入を提供してください。これは API の潜在的な利用者の最初の入り口となるため、API が提供する価値 (何をするのか、どのような問題を解決するのか、API を操作することでエンドユーザーがどのような結果を期待できるのか) に焦点を当てるようにしてください。このセクションを詳細に説明する際には、利用者が解決しようとしている課題について考えてください。このようにすることで、概要セクションのメッセージがターゲットオーディエンスに本当に響くようになります。
以下は、API 開発者エクスペリエンスに関する最近のSwaggerHub ウェビナーからの説明例です。 
開始ガイド
開始ガイドには、API キーまたはクライアントトークンのアクセス方法、および API の利用規約に関する情報が記載されています。API の UI に加えて、サポートやフィードバックの共有のためにチームに連絡する方法に関する他の参考資料や詳細へのリンクを含めることができます。このガイドは、利用者が成功を収めるために手厚くサポートする必要があります。利用者が API の価値を5分以内に理解できるようなガイドを作成することをお勧めします。SwaggerHub の顧客である Bandsintown の例を考えてみましょう。Bandsintown は、SwaggerHub からそのパブリック API ドキュメントをウェブサイトで公開しています。 
開始ガイドは、Bandsintown API を立ち上げて実行するために必要なガイダンスを提供します。Braintree や YouTube のような企業からの役立つ例もあり、これらの企業は開発者が API を操作する方法を理解するためのヘルプセクション全体を構築しています。
リクエスト・レスポンスサイクルの説明
多くの API チームは、API エンドポイントの記述に関しては最低限のことしか行いません。API を視覚化するために必要な基本的なフレームワークを生成するだけで、ユーザーがそれらを操作する方法を理解するのに役立つ具体的な詳細は追加しません。これは以前は機能したかもしれませんが、新しい API やソリューションが日々登場する今日の競争の激しい環境では、ユーザーにはさまざまな選択肢があり、完全な情報が提供されるに値します。
サポートされているすべての形式で完全なサンプルレスポンスボディを記述してください。これには、XML または JSON データ形式だけでなく、HTTP ヘッダー、エラーコード、メッセージも含まれます。潜在顧客やエンドユーザーが API を使用する方法を学ぶのに役立つ情報を多く提供することは、決して悪いアイデアではありません。優れた API ドキュメントの目標は、ターゲットオーディエンスが API を操作する方法を理解するために必要な情報を提供することであることを忘れないでください。必要に応じて、詳細な説明と使用例を含める必要があります。
技術的またはドメイン固有の専門用語がある場合は、その特定の項目を、これらの用語を説明する追加のドキュメントにリンクしてください。これらの戦術は、API 全体の明確さと優れた構造を保証し、特定の呼び出しが存在する理由を、パラメーター、ヘッダー、レスポンスの詳細に迷うことなく説明します。
SDK とコードライブラリへのリンク
SDK ライブラリは、ユーザーが API とより速く統合するのに役立ちます。これらは、ユーザーが API の操作を簡単に使用し、それらの上に豊富な機能とアプリケーションを構築できるようにするのに最適です。すでに OpenAPI 仕様で API を定義している場合は、SwaggerHub のようなプラットフォームを使用してサーバーサイドコードとクライアント SDK を生成し、API の採用を増やすのに役立てることができます。
ワンクリックで、SwaggerHub は HTML テンプレートを生成し、API のドキュメントと開発者ポータル用の6つのクライアント SDK 使用例を提供します。これにより、開発チームは簡単にカスタマイズ、対話、作業を行うことができます。SwaggerHub の組み込みコードジェネレーターを使用して、30以上の言語に SDK を追加することもできます。 
SwaggerHub で API ドキュメントをさらに活用しましょう
すでに Swagger を使用して API のインタラクティブな UI を生成している場合は、SwaggerHub のようなAPI ドキュメンテーションツールを使用して、API ドキュメントを次のレベルに引き上げるのに適しています。SwaggerHub は、すべてのインフラストラクチャの考慮事項とセキュリティの実装を排除し、組織がシームレスに協力して、ユーザーと開発チームが気に入る優れた API ドキュメントを作成できるようにします。SwaggerHub での API ドキュメント作成の詳細をご覧ください。または、今すぐ SwaggerHub を無料で試してください。