API の設計と開発には、説明の繰り返しと書き直しがかなりの量で伴います。開発者、組織、または独立したチームは、さまざまな API 設計で再利用される多数のこのような再利用可能なコンポーネントを持つことになり、それらを絶えず書き直すことは退屈でイライラする可能性があります。ここで SwaggerHub Domains が役立ちます。簡単に言えば、Domains は再利用可能なコンポーネントのコレクションです。Domain 内に保存できるコンポーネントは次のとおりです。
- 定義 : これらは API の入力と出力を記述するモデルです。
- パスアイテム: パス間で再利用できる一連の定義済み操作
- パラメータ: API への入力
- レスポンス: API 呼び出しからの出力
SwaggerHub 上の Domains は、API と同じ方法で管理されます。ユーザーは Domains を作成してバージョン管理し、その中にコンポーネントを定義できます。コンポーネントは、ユーザーまたは API の共同作業者によって、他の API または Domains から参照できます。Domains は、複数の API のコントロールセンターとしても機能し、Domain の変更は、その Domain を参照するすべての API にすばやく伝達され、API の開発と共同作業を高速化できます。
Domain の作成と使用
すべての Domain には、所有者、名前、およびバージョンがあります。新しい Domain は、右上隅にある「Add New Domain」をクリックして作成できます。
Domain に適切な名前とバージョンを設定したら、ユーザーは Domain 内に必要なコンポーネントを追加できます。コンポーネントが配置されたら、Domain を公開できます。開始に役立つサンプル Domain を以下に示します。公開された Domain は、他の Domain や API から確実に参照できます。自分の Domain を参照するのは簡単です！参照を開始し、SwaggerHub の新しい自動提案機能で適切な Domain とコンポーネントを選択するのを手助けしてもらいましょう。参照したい Domain のオブジェクトの名前を入力し始めると、自動提案が表示されます。以下は、入力内容に基づいて最も可能性の高いオブジェクトを自動提案が表示する方法です。
以下の構文を使用して、公開または共有されたプライベート Domain を直接参照することもできます: $ref: 'https://api.swaggerhub.com/domains/{ownerId}/{domainName}/{domainVersion}#/{componentType}/{componentName}'
Domain の管理
作成された Domains は、編集したり、異なるバージョンに更新したり、Github にプッシュしたり、削除したりできます。Domains はパブリックまたはプライベートのいずれかになります。パブリック Domain は、他の Swaggerhub ユーザーが検索、表示、参照、フォークできますが、プライベート Domain は、あなたと追加した共同作業者のみが閲覧および作業できます。ユーザーは検索バーで「Search Domains」を選択して、他のユーザーによって公開された Swaggerhub 上の優れたパブリック Domain を検索できます。
Domains は API デザイナーの作業を容易にします。SwaggerHub で試してみて、さらに質問がある場合は、機能ドキュメントまたはFAQ セクションを参照してください。