SwaggerHubのCompare & MergeでAPIドキュメントワークフローを改善する

SwaggerなどのAPI記述形式は、APIプロバイダーとエンドコンシューマー間の契約として機能し、APIのすべてのリソースと操作を、人間と機械の両方が読み取り可能な形式で明確に詳細に記述します。Swaggerを使用してRESTful APIを文書化することで、開発が容易になり、検出性が向上し、エンドコンシューマーにとって全体的により良い統合体験が可能になります。 APIを定義するためにSwaggerを使用するプロバイダーは、その契約を最新の状態に保つ責任があり、そのためにはSwagger定義の複数のバージョンを管理する必要があることがよくあります。 あるいは、「コードファースト」アプローチでSwaggerを導入している場合（APIのコードからアノテーションを使用してSwagger仕様を生成する必要がある場合）は、APIの優れた定義を作成するためにいくつかの調整が必要になることがあります。 どのようなアプローチでSwaggerを使用してAPIを定義する場合でも、プロセスにはさまざまなスキルセットと責任を持つ複数の人々が関与する可能性が高いです。

APIドキュメント作成に適切な人材を巻き込む

ドキュメントワークフローに最適なツール

SwaggerHubに比較とマージ機能を導入

1. SwaggerHubで、APIを編集用に開きます。必要なバージョンに切り替えます。
2. エディターの右上隅にある「歯車」アイコンをクリックし、メニューからAPIの比較とマージを選択します。
3. 次のダイアログで、SwaggerHubの仕様と比較を選択します。
4. 次のダイアログで、比較するユーザー名、API、およびAPIバージョンを指定します。

1. 「次へ」をクリックします。SwaggerHubはAPIがアクセス可能であることを検証します。

1. SwaggerHubで、APIを編集用に開きます。必要なバージョンに切り替えます。
2. エディターの右上隅にある「歯車」アイコンをクリックし、メニューから「APIの比較とマージ」を選択します。
3. 次のダイアログで、外部の仕様と比較
4. 次のダイアログで、目的のJSONまたはYAML APIのURLを入力するか、ハードドライブ上のAPIファイルを指定します。
5. 「取得」をクリックします。SwaggerHubは指定されたAPIをロードし、それが有効かどうかをチェックします。

1. ウィンドウの右または左の部分で、強調表示された差分行（またはブロック）をクリックします。SwaggerHubは、ブロックをウィンドウの左側から右側（つまり、あなたのAPI）にコピーし、強調表示を削除します。また、元に戻すボタンのカウンターも増加します。
2. 必要に応じて、元に戻すをクリックして、最近の承認を取り消します。複数の承認を取り消すには、「元に戻す」を複数回クリックします。
3. 必要な差異をすべてマージした後、「変更を保存」をクリックして変更を保存します。これにより、元のAPI仕様が変更されたものに置き換えられます。