SwaggerHub - FAQ

SwaggerHub に関する 「よくある質問とその回答」 です。

探しているものが見つかりませんか? コミュニティ フォーラムをご参照ください。

 

FAQ カテゴリ


 

全般的な質問

Q1. SwaggerHub とは何ですか?

SwaggerHub はチーム用に構築された統合 API 開発プラットフォームで、Swagger フレームワークの中核機能を使って API を設計、構築、文書化、デプロイします。 SwaggerHub を使用すると、開発チームは、選択したツールセットと柔軟に統合して、API のライフサイクル全体を共同で調整できます。

Q2. SwaggerHub は無料ですか?

無料版と有償版があります。 API は開発者にとって世界をより良い場所にし、SwaggerHub はユーザーがその多くの機能を無料で利用できるように設計されています。 有料のプレミアム機能があり、それらは簡単に年間サブスクリプションを購入することができます。 必要に応じていつでも無料にダウングレードできます。

API を作成するには、SwaggerHub アカウントを作成する必要があります。SwaggerHub Web サイトの右上にある [Sign Up] ボタンをクリックするだけです。

Q3. GitHub / Bitbucket / GitLab を使っています。 これはどう違うのですか?

ソース管理はソースに最適です。 しかし、API 定義はまったく同じではありません - それらは独自の、特別の扱いが必要です。 SwaggerHub はバージョン管理システムと連携して動作するため、ソースコードを探し求めることはもう必要ありません。

SwaggerHub は GitHub、GitLab、Bitbucket への接続が可能です。 統合についての詳細はこちらをご覧ください

Q4. プライベートな API では、何ができますか?

プライベート API は有料プランで利用できます。 必要な API と共同作業者の数に基づいたサブスクリプションが用意されています。 いつでも様々な機能を試すために無料トライアルを始めることができます。 サブスクリプションとトライアルの詳細については、価格ページをご覧ください。

Q5. API に追加できる共同編集者の数に制限はありますか?

はい、共同編集者の数は限られており、ご利用のサブスクリプション プランに基づいています。共同編集者の数の詳細については、価格ページをご覧ください。

 

ページ トップに戻る

SwaggerHub の利用

Q1. SwaggerHub ではどのブラウザーを使用できますか?

Chrome、Firefox、Safari、Edge の最新バージョンを正式にサポートしています。 他のブラウザーや古いバージョンでも動作する可能性はありますが、互換性は保証されていません。

Q2. Swagger には 2 つの異なる UI があるのはなぜですか?

実際、Swagger 定義を扱うためのユーザーインターフェースは 2 つあります。 [Editor] タブでは、コンテンツに対する自動コンテキスト候補を YAML ベースのテキストエディターで提供します。 画面の右側にはライブ レンダリングが表示され、作成している API 定義を簡単に視覚化できます。

あるいは、[UI] タブには、API の利用者向けに調整された、API の読み取り専用ビューが表示されます。 これらの異なるビューが API の意図を理解するために高い柔軟性を与えます。

Q3. API の発行 (パブリッシング) とは何をするのですか?

API を作成し、それをユーザーが使用できるようにするとき、そのユーザーに対する契約が作成されます。 彼らはある特定の方法で動作させるためにその定義に頼っています、そして変更して破ると、統合が中断される可能性があります。

API のパブリッシングは、単一バージョンの API に固有のものです。 API が出荷され、ユーザーが署名に頼ることができるときにそうするべきです。 それはチームと消費者に API が安定した状態であることを示します。 一旦、パブリッシュされると読み取り専用になり、変更できません。

公開したら、API の新しいバージョンで変更を加えることを検討すべきです。

公開した後は、デフォルト バージョンの API を更新したいと思うかもしれません。 これは検索結果に表示されるもの、または特定のバージョン番号なしでユーザーが直接 API にアクセスした場合です。 バージョン管理の詳細については、こちらを参照してください

もちろん、あなたがタイプミスをしているか、または緊急の変更を加える必要があるかもしれない予想外の状況がいつもあります。 API を Unpublish (非公開) にすることはできますが、慎重に行ってください。ユーザーとの信頼関係は貴重です。

API の公開についての詳細はこちらをご覧ください

Q4. SwaggerHub はバージョン管理をサポートしますか?

はい、あなたは API をバージョン管理し、古い API 契約を廃止することができます。 API のバージョン管理の詳細については、こちらを参照してください

Q5. API の名前とタイトルの違いは何ですか?

API の Name フィールドは、SwaggerHub の API を一意に識別するために使用されます。設定した後は変更できません。 permalink のこの部分を API 定義で考慮してください。また、それは SwaggerHub Public API を通して定義へプログラム的にアクセスするためにも使用されます。

 

ページ トップに戻る

コラボレーション

Q1. 定義を他のユーザーと共有する必要があります。 どうすればいいですか?

パブリック定義とプライベート定義の両方を他のユーザーと簡単に共有できます。 これらのユーザーはシステム内で共同編集者 (Collaborators) と呼ばれ、API への読み取り専用または読み取り/書き込みアクセス権を持つことができます。

コラボレーションの詳細についてはこちらをご覧ください

Q2. SwaggerHub を社内でどのように使用できますか?

SwaggerHub は組織の概念をサポートしています。各組織は、ユーザーを論理グループに追加できるチームを作成できます。 API には、個人に対して、またはチームに対して一括して権限を付与できます。

組織についての詳細は、こちら

Q3. 自分の定義を外部からアクセスする必要があります。 どうすればいいのですか?もしそれらがプライベートだったら?

パブリック SwaggerHub API からいつでもパブリック API にアクセスできます。 API アクセス自体は、ここで定義されています。

swaggerhub-registry

簡単に言えば、あなたの API はこのパターンを通してアクセスできます。

https://api.swaggerhub.com/apis/{owner}/{api}/{version}

ここに行くことによって、いつでもすべての API を操作することができます:

https://api.swaggerhub.com/apis/{owner}

これは apis.json 形式で応答を返します。

アクセス可能な保護された API の場合は、SwaggerHub から API キーを取得し、それを使用して保護された API 定義にアクセスできます。 API キーを取得するには、設定に進みます。 それから、データにアクセスするときにヘッダーとして使用できる API キーを生成できます。例えば:

curl -H Authorization:YOUR_API_KEY https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.10

この定義の JSON バージョンを返します。 YAML が必要なら、Accept ヘッダでそれを伝えてください:

curl -H Accept:application/yaml -H Authorization:YOUR_API_KEY https://api.swaggerhub.com/apis/swagger-hub/registry-api/1.0.10

注意: このトークンはあなたのデータにアクセスできるので、安全な場所に保管してください。

Q4. クライアント SDK をダウンロードしました。 次に何をしたらいいですか?

これは、作業している言語によって異なります。一般に、クライアント SDK はそれ自体では有用ではありません。 プログラムを使用して直接呼び出すことをお勧めします。 各言語とフレームワークで、使用方法が異なります。 出力ファイルの中の README.md を参照してください - それはあなたが始めるのを助けます。

 

ページ トップに戻る

統合 (インテグレーション)

Q1. 統合 (インテグレーション) とは何ですか?

統合は、SwaggerHub 上の API 定義にその機能を改善および拡張するための無料のアドオンです。 これらの統合は、SwaggerHub 上での API 設計だけでなく、自分の API を多数のサードパーティ製ツールに接続するのに役立ちます。 定義を GitHub リポジトリと同期したり、Swagger 定義のモックをすばやく生成したり、SwaggerHub 上の特定のイベントをトリガーする Web フックを作成したりできます。

詳細は、こちら

Q2. 同じ API に複数の統合を追加できますか?

はい、同じ API に複数の統合を追加できます。統合は異なる場合があります。たとえば、API で GitHub Sync と Webhook 統合を有効にすることができます。 API では、同じ統合を 2回有効にすることもできます。たとえば、2 つの異なるAmazon API Gateway 統合を同じ API に追加して、API を 2 つの別々の Gateway インスタンスと同期させることができます。

Q3. Auto-Mocking Integration ではビジネス ロジックを追加できますか?

いいえ、現在の状態では、VirtServer 統合によって生成されたモックは、入力に基づいた特定の応答を送信することはできません。

 

ページ トップに戻る

ドメイン

Q1. ドメインとは何ですか?

API 開発者は、API 開発に定義と説明の再利用と書き換えがたくさんあることを知っています。 ドメインはそのような再利用可能なコンポーネントの集まりであり、他の API やドメインから参照することができます。 ドメイン内に以下のコンポーネントを格納できます:

  • 定義
  • Path 項目
  • パラメーター
  • 応答

ユーザーはドメインを作成およびバージョン管理してから、その中のコンポーネントを定義できます。 コンポーネントは、ユーザーまたは API の共同作業者によって、他の API またはドメインから参照できます。 ドメインは複数の API のコントロールセンターとしても機能します。 ドメイン内の 1 回の変更で、そのドメインを参照しているすべての API 間で変更を迅速に伝達できるため、API の開発とコラボレーションを迅速化できます。

ドメインに関する詳細は、こちら

Q2. 誰が私のドメインを見ることができますか?

ドメインには、プライベートとパブリックの 2 種類があります。名前が示すように、パブリック ドメインは他の SwaggerHub ユーザーが検索、表示、参照、およびフォークすることができますが、プライベート ドメインはあなたと追加した共同編集者によってのみ表示および操作できます。 すべてのユーザーに 2 つの無料パブリック ドメインを提供しています。 詳細は、サブスクリプション販売をご確認ください。

Q3. 自分のドメインから他のドメインを参照できますか?

あなた自身のドメインと、他のユーザによってあなたと共有されているパブリックまたはプライベート ドメインであるドメインを参照することができます。 現在、ドメインは他のドメインへの絶対参照を必要とします。 あるドメインから別のドメインを参照するには、以下の構文に従ってください。

$ref: 'https://api.swaggerhub.com/domains/{ownerId}/{domainName}/{domainVersion}#/{componentType}/{componentName}'

Q4. 他のドメインを検索する方法は?

SwaggerHub の他のユーザーは、パブリック ドメインを検索、表示、参照、およびフォークすることができます。ユーザーは検索バーで [Search Domains] を選択して、他のユーザーが公開した SwaggerHub 上のいくつかの優れたパブリック ドメインを検索できます。

 

ページ トップに戻る

トライアル版、無償版

Q1. 無料版と Pro 版の SwaggerHub の違いは何ですか?

SwaggerHub 無料アカウントは、SwaggerHub プラットフォームを試し、エディターに慣れ、API の設計と文書化を始めるための最良の方法です。 SwaggerHub の Pro アカウントは、複数の API を管理し、プライバシー、バージョン管理、可視性管理などの追加機能を必要とするチーム、組織、企業向けに構築されています。

Q2. トライアル版はどのくらい利用できますか?

上記の表に概説されている制限に達するまで、無料アカウントは無料です。 あなたはいつでも Pro 版を試用したりアップグレードすることができます。 トライアルでは、SwaggerHub を 14 日間評価できます。

Q3. チーム メンバーが SwaggerHub で私の API を表示するには、チーム メンバーは SwaggerHub アカウントが必要ですか?

パブリック定義とプライベート定義の両方を他のユーザーと簡単に共有できます。 これらのユーザーはシステム内で共同編集者 (Collaborators) と呼ばれ、API への読み取り専用または読み取り/書き込みアクセス権を持つことができます。 特にパブリック API の場合は、API を表示するために登録ユーザーになる必要はありませんが、API 仕様を編集またはコメントする場合はアカウントを作成する必要があります。 プライベート API の場合は、API 仕様を表示、編集、またはコメントするには、登録ユーザーになる必要があります。

Q4. 私の個人的なプロジェクトでの私の作業は私のトライアルが終わるときどうなりますか?

心配しないでください - あなたの作業は SwaggerHub に保存されます。 無料のアカウントで API を操作することはできませんが、有料プランにアップグレードすると、あなたの作業を継続できます。

Q5. SwaggerHub は、Swagger Editor、Swagger UI、Swagger CodeGen などのオープン ソース ツールとどう違うのですか?

SwaggerHub は、オープン ソースの Swagger ツールをすべてクラウド内の 1 つの使いやすいプラットフォームにまとめたものです。 SwaggerHub を使用すると、API を設計、文書化、または構築するための追加のツールをダウンロードする必要はありません。 さらに、他のプラットフォームと統合して API を同期およびデプロイすることはできます。 SwaggerHub を使用すると、クラウドで API を保存およびバックアップすることもできます。

Q6. 既存の API がありますが、SwaggerHub をどのように使用できますか?

既存の Swagger 定義を SwaggerHub にインポートできます。 SwaggerHub 内では、既存の API を文書化して仕様を繰り返すことができます。

Q7. SwaggerHub プライベート クラウド / エンタープライズ プランの詳細を知るにはどうすればよいですか?

SwaggerHub のエンタープライズ機能について知る最良の方法は、Web ページのお問い合わせから連絡することです。

 

ページ トップに戻る