SwaggerをHATEOAS / HAL / JSON-LDと組み合わせる必要がありますか？
私はSwashbuckleを使用してASP.NET Core APIにSwaggerを使用しています。Swashbuckleは、私のAPIを別のドキュメントで説明し、このすべての情報に素敵なUIを提供します。
Swaggerと組み合わせてドキュメント自体を変更するHATEOAS、HAL、JSON-LDなどを使用する利点はありますか？
ここ は、HALでSwaggerを使用しているユーザーの例です。
Sampadaが両方を述べたように-swaggerとHATEOAS-は、apiのさまざまな次元により多くの価値を追加します。
Swaggerは、開発ライフサイクルに価値を追加し、開発時にAPIをより理解し、参照可能にします。
[〜＃〜] hateoas [〜＃〜]を使用すると、APIに値が追加されますクライアント。 HATEOASが提供するリンクを使用すると、アプリのクライアントコードでそれらのリンクをハードコーディングする必要なく、APIのさまざまな部分（つまり、リソース）をリンクできます。
あなたはそれに関連するいくつかの文書と契約を結んでいると仮定します。これをモデル化する非常に一般的な方法の1つは、2つのリソースを使用することです。
- 契約リソース-契約を一覧表示、追加、削除、変更する操作が与えられます。
- ドキュメントリソース-ドキュメントの一覧表示、追加、削除、変更の操作が与えられます
これら2つをリンクするには、関連するリソースの配列を含む両方のリソースモデルにフィールドを追加します。さらに、クライアントアプリケーションにもこれらの暗黙の知識を実装する必要があります。このようにして、（時間の経過とともに）リソース表現に混乱を追加し、他のオブジェクトとの関係に関する情報でそれを汚染します。
これがHATEOASの出番であり、それらの実在情報をビジネスオブジェクトから移動し、それらの関係を処理するための統一された方法を提供します。両方のリソースビジネスオブジェクトに、1つのstandardizedヘッダーまたはall関係に関する情報を含む値フィールドが含まれるようになります現在のリソースの。例えば。 1つの契約リソースには、適切なドキュメントリソースにリンクするrel属性「ドキュメント」とのリンクが3つと、この契約が発生した注文にリンクするrel属性「注文」とのリンクが1つあります。
私の知る限りJSON-LDは、さまざまなAPIの語彙を正規化するために使用され、並べて使用する方が簡単です。 firstName＆lastNameをPersonオブジェクトのプロパティとして使用するものもあれば、呼び出されたプロパティgivenName＆familyNameを持つものもあります。 JSON-LDを使用すると、両方のオブジェクトを共通名にマップできます。あなたはこのリンクを見ることを検討するかもしれません： DZone-Json-LD
HATEOASを使用することに加えて、SwaggerをAPIコードに統合することの明確な利点があります。
Swaggerは、クライアントコードを簡単に記述できるように見栄えをよくすることでAPIにフォームを追加すると同時に、コードをコードと統合することでドキュメントの退屈な作業を大幅に減らします。言うまでもなく、コーディングが完了した後に文書化する場合にかかる余分な時間も節約できます。この意味で、それは少し革新的です。
一方、HATEOASは レベル3 RMM を有効にすることで、APIを自己検出可能にします。これにより、あるAPIから別のAPIに簡単に移動できます。アイデアは、クライアントが使用できるベースURLを持ち、残りのREST APIがこのベースURLから発見されることです。
今問題は、なぜ両方があるのですか？まあ、それはあなたのRestful APIにより多くの次元を追加し、ごくわずかなコーディングの努力のためにクライアントにより多くの選択肢を与えます。誰がそれを望まないのでしょうか？
Hydraの調査を検討してください。
HydraはJSON-LDの語彙であり、ハイパーメディアコントロールをデータに埋め込むことができます。さらに、Swagger定義と同様の役割を果たすAPIドキュメントエンドポイントを提供できます。 Hydraで私が気に入っているのは、ハイパーメディアコントロールが、ある種のサービス定義では帯域外に住んでいるのではなく、応答に組み込まれていることです。 JSON-LDとSchema.orgは、GoogleとMicrosoftの両方が製品でそれらをどのようにサポートしているかを考えると、検討する価値があります。
Hydraはまだ比較的新しいため、使用可能なツールはSwaggerほど強力ではありません。