ホーム ブログ SwaggerHub 101のまとめ...

SwaggerHub 101のまとめ：SwaggerHubに関するよくある質問への回答

ライアン・ピンカム
  2016年10月4日

先日、SwaggerHubユーザー向けの無料トレーニングを開始しました。これらのトレーニングは、SwaggerHubのさまざまな機能とプラットフォームの機能を紹介することで、SwaggerHubを最大限に活用できるよう設計されています。今後のSwaggerHub 101トレーニングの全リストはこちらで確認できます。トレーニングの一環として、参加者はSwaggerHubチームのメンバーに質問する機会があります。最近のSwaggerHub 101トレーニングで寄せられた主な質問のまとめを以下に示します。

「コメントを表示」とは何ですか？また、どのように機能しますか？

コメント機能は、SwaggerHubに組み込まれているコラボレーション機能の1つで、さまざまな関係者がSwaggerHub Editor内でAPI定義にコメントを付けることができます。コラボレーターには、API設計プロセスに参加するために必要なアクセス量に基づいて、特定の役割を割り当てることができます。たとえば、コラボレーターには、APIを編集する機能（Editor）、Swagger仕様の個々の行にコメントを付ける機能（Commentator）、またはAPIを単に表示する機能（Viewer）を付与できます。SwaggerHubエディターでAPI定義の特定の行に関するアイデアを議論したり、問題点を指摘したりするためにコメントを使用します。 comments コメントはフィードバックを共有したり、問題を提起したりするために使用でき、未解決または解決済みとしてマークできます。「コメントを表示」ボタンは、未解決と解決済みの両方のすべてのコメントを表示します。 SwaggerHubとのコラボレーションの詳細については、こちらをご覧ください。

SwaggerHubはJSONまたはYAMLをサポートしていますか？

SwaggerHubは、APIを記述するためのSwagger (Open API) 2.0構文をサポートしています。API定義のデフォルトの形式はYAMLです。JSONテキストも貼り付けることができますが、API定義を保存するとYAML形式に変換されます。Swagger仕様は、両方の形式（YAMLとJSON）でダウンロードできます。

SwaggerHubでAPIを公開するとどうなりますか？

公開とは、APIが安定した状態であり、設計どおりに機能し、アプリケーションで利用できることを伝える方法です。SwaggerHubでAPIを公開すると、そのAPIは読み取り専用になり、再度非公開にしない限り編集できません。説明テキストを改善したり、誤字を修正したりする必要がある場合は、一時的にAPIを非公開にしても問題ありません。しかし、新しい操作やパラメーターのような破壊的変更の場合は、SwaggerHubエディターのAdd Version コマンドを使用して、代わりに新しいバージョンを開始する必要があります。SwaggerHubを使用すると、API仕様の複数のバージョンを管理できるため、公開されているバージョン（「本番」バージョン）をそのままにしながら、次のAPIバージョンに取り組むことができます。SwaggerHubでのAPI公開の詳細については、こちらをご覧ください。

SwaggerHubで利用可能な統合は何ですか？

SwaggerHubは、チームがAPIライフサイクル全体でコラボレーションできるように構築されています。その結果、SwaggerHubは、チームがAPIを開発するために信頼するツールをサポートしています。これらの統合には以下が含まれます。 SwaggerHubで利用可能な統合の詳細については、こちらをご覧ください。

APIバックエンドサーバーをモックするにはどうすればよいですか？

SwaggerHubはVirtServerと統合しており、これはSmartBear Ready! API仮想化製品の一部です。有効にすると、VirtServer統合はSwaggerHubで定義されたAPIの半静的モックを自動的に作成および維持します。このモックはAPIを保存するたびに更新されるため、モックサービスを作成するために外部ツールを見つけて使用する必要がなくなります。数回のクリックで、VirtServerによって生成されたプレビューを使用して、チームと効率的に設計を反復できます。モックサーバーは、API設計を検討する際に強力なツールとなります。コードを1行も書かずに、APIコンシューマーがVirtServerに対してクライアントを開発することを許可できます。これにより、互換性のある現実的なペイロードで応答することが保証されます。SwaggerHubでのAPIモックの詳細については、こちらをご覧ください。

SwaggerHubはAPIのドキュメント作成にどのように役立ちますか？

SwaggerHubは、ドキュメントに関して次の機能を提供できます。
  1. ユーザーは、Swagger EditorでAPIのあらゆる側面を直接定義およびドキュメント化でき、それらがInteractive Docsタブでエンドコンシューマーが操作、理解、統合できるように視覚的にレンダリングされるのを確認できます。
  2. ユーザーは、APIの組み込みHTMLダウンロード機能を使用して、基本的な開発ポータルのようなインターフェースを生成できます。APIドキュメントのブートストラップバージョンをダウンロードでき、これには6種類のクライアントSDKを備えたエンドポイントが表示され、さらに追加することも常に可能です。  
swaggerpetstore2 HTMLレンダリングを取得する手順は次のとおりです。 ステップ1：SwaggerHubで有効なAPIのいずれかに移動します。 ステップ2：右上隅のダウンロードアイコンをクリックし、クライアントサイドダウンロードからhtml2オプションを選択します。 publish-swagger ステップ3：  zipファイルをローカルマシンの既知の場所にダウンロードします。ダウンロード場所に移動し、フォルダーを解凍し、ダウンロードして解凍したフォルダー内にあるHTMLファイルを開きます。

オンプレミスSCMシステムに接続できるデプロイ済みバージョンを提供する計画はありますか？

はい、SwaggerHubのオンプレミスバージョンはすでに利用可能です。これは、Enterprise SwaggerHubプランの一部です。オンプレミスバージョンがお客様の組織に適しているかどうかを確認する最善の方法は、SwaggerHubチームに直接[email protected]までお問い合わせいただくことです。

トレーニングを見逃しましたか？オンデマンドで視聴できます。

または、今後のトレーニングに登録してください。
SwaggerHubに関する追加の質問がありますか？[email protected]までメールでお問い合わせいただくか、Twitterでご連絡ください：@SwaggerHub。

こちらもおすすめ