以前にも述べた通り、可視化されたAPIは再利用され、再発明されることはありません。開発者がAPIを簡単に操作できるようにすることは不可欠です。
これを実現するには、明確なドキュメントと役立つリソースを提供する必要があります。そこでSwaggerHub Portalの出番です。プロセスを簡素化し、開発者が作業をより簡単に行えるようにします。
なぜポータルなのか？
SwaggerHub Portal APIを使用すると、APIを簡単に製品化できます。オンボーディングガイド、リソース、ドキュメントを含むブランドのランディングページを作成し、消費者がAPIを理解し、アプリケーションに統合するのに役立ちます。
SmartBear Portalを使用してセットアッププロセスを自動化し、ポータルを稼働させることができます。SwaggerHub Portal APIを使用すると、開発者にクラス最高の開発者体験 (DX) を提供できます。ユーザーフレンドリーなインターフェースとインタラクティブなドキュメントにより、APIの採用が加速します。
はじめに
詳細に入る前に、いくつかの前提条件を以下に示します。
- SwaggerHubアカウント: EnterpriseライセンスのSwagger Hubアカウントが必要です。
- ユーザーロール: APIを呼び出すには、SwaggerHub組織内でデザイナーまたはオーナーのロールが必要です。
- SwaggerHub Portalの有効化: Swagger Hub Portalは組織で有効になっている必要があります。
これらの前提条件が整っていれば、SwaggerHub Portal APIを使用して開発者ポータルの構成プロセスを自動化する準備が整いました。
認証
Portal APIと連携するには、SwaggerHubからAPIキーが必要です。このAPIキーは、作成する各APIリクエストの「Authorization」ヘッダーに「Bearer [your_api_key]」として含める必要があります。
開発者ポータルの設定
最初のステップの1つは、開発者ポータルの外観をカスタマイズすることです。API経由でのブランド画像のアップロードはまだ利用できませんが、アクセントカラー、フォント、ランディングページの説明を設定できます。
- ポータル識別子の取得: ポータル設定を管理するには、「portals」APIリソースへの呼び出しを使用してポータルインスタンスの識別子を取得する必要があります。
- ポータル設定の設定: 取得したポータルIDを使用して、PATCHリクエストを介してポータルの設定を更新します。アクセントカラー、フォント、ランディングページの説明を調整できます。
製品の追加
製品は開発者ポータルの重要なコンポーネントです。Swagger Hub Portal APIを介して、API定義やドキュメントを含む製品コンテンツを管理できます。
- 製品の作成: 「products」エンドポイントにPOSTリクエストを送信して、新しい製品を作成します。ポータルID、製品名、説明、スラッグ、その他の関連詳細を含めます。
- ロゴの追加: ポータル全体のブランドを強化するために、会社ロゴを簡単にロゴを追加できます。
製品コンテンツの入力
製品を作成したら、API定義やドキュメントを含むコンテンツを入力します。
- セクションの作成: セクションはコンテンツのプレースホルダーとして機能します。「sections」エンドポイントにPOSTリクエストを送信し、製品のセクションを指定します。
- APIの追加: セクションの「目次」にPOSTリクエストを使用してAPI参照を追加します。タイトル、スラッグ、コンテンツ (通常はOpenAPI定義への参照) を含めます。
- ドキュメントの追加: 包括的なドキュメントを提供するには、技術的なAPI参照に加えてMarkdownドキュメントを追加します。セクションにPOSTリクエストを送信しますが、今回はMarkdownコンテンツを含めます。
- コンテンツの公開: 最後に、製品コンテンツを公開してポータルでアクセスできるようにします。製品の公開コンテンツを更新するリクエストを送信します。
次のステップ
Portal APIを使用すると、開発者ポータルの構成と管理を合理化できます。製品の追加、コンテンツの更新、ポータルの外観のカスタマイズなど、これらのAPIはプロセスを自動化し、開発者体験を向上させる強力な方法を提供します。
Portalを使用すると、空の開発者ポータルをAPIドキュメントとリソースのユーザーフレンドリーなハブに変えることができます。このセルフサービスアプローチは、開発チームの能力を高め、APIの採用を加速します。
今日からPortal APIをワークフローに組み込んで、開発者ポータルを強化し、開発者が成功するために必要なツールを提供しましょう。詳細なステップバイステップのセットアップガイドについては、SwaggerHub Portal API入門をご覧ください。
無料で試す！