ドキュメントサイトの公開

ドキュメントサイトの公開は、クイック共有機能の使用とは異なります。クイック共有は内部および外部のパートナーに共有可能なリンクを生成し、一時的なコミュニケーション手段として機能しますが、長期的な使用を目的としていません。

それに対して、ドキュメントサイト 機能はより堅牢なカスタマイズを可能にします。ドメイン名、ページデザイン、ナビゲーションなどを個別に設定できます。この機能は、公式ウェブサイトでAPIドキュメントを公開する必要がある場合に最適です。

ドキュメントサイトの公開

デフォルトのメインサイトをクリックし、公開ボタンをクリックします。

ドキュメントサイトの可視性設定

Apidogのバージョンは≥ 2.7.15である必要があります。

公開ボタンをクリックした後、ニーズに応じて公開されたドキュメントサイトの可視性を簡単に制御できます。今すぐ公開 ボタンをクリックするだけで、サイトを公開できます。

公開

ドキュメントサイトはすべてのインターネットユーザーがアクセス可能になります。また、Apidogが運営するプラットフォームAPI HubでAPIドキュメントを公開することも選択できます。

パスワード保護

APIドキュメントをパスワードで保護したい場合は、Password protectedを有効にしてパスワードを設定します。自分で作成するか、ランダムに生成することができます。

password protected API documentation.png

IP ホワイトリスト

特定のIPアドレスまたは範囲にのみドキュメントサイトへのアクセスを制限します。

メールホワイトリスト

設定したメールホワイトリストにあるメールのみが、認証コードを通じてメールを確認することでドキュメントサイトにアクセスできます。メールホワイトリストトはワイルドカードをサポートしており、企業メールのアクセス管理が容易です。

カスタムログインページ

ユーザーがオンラインドキュメントサイトにアクセスする前に独自のログインシステムを通じて認証を行いたい場合、カスタムログインページ機能を有効にできます。

設定ガイド

ドキュメントサイトの可視性設定に移動し、カスタムログインページを選択し、次の2つのフィールドを入力します：

JWT Secret: トークンの署名を検証するために使用されます。バックエンドがJWTを発行する際に使用するシークレットと同じでなければなりません。このシークレットは自分で生成する必要があります。

ログインURL: ユーザーがオンラインドキュメントサイトにアクセスすると、このURLにリダイレクトされます。このアドレスにログインページをホストし、バックエンドで認証とトークン生成を実装する必要があります。

このログインページはApidogが提供するものではありません。自分で構築し、ホストする必要があります。

認証ワークフロー

JWT（JSON Web Token）はユーザー認証のためのオープンスタンダードです。ログインシステムは以下のフローに従う必要があります：

ユーザーがApidogによって公開されたオンラインドキュメントサイト（例：https://xxxxx.apidog.io）を訪問します。

システムは自動的に設定されたログインページ（例：http://localhost:3000）にリダイレクトします。

ユーザーが資格情報を入力し、フォームを送信します。

バックエンドがユーザーの資格情報を検証します。

認証が成功すると、バックエンドは設定されたシークレットを使用して署名されたJWTを生成します（例：pJRdFC3amihQdWbHvUXNZG9WzYdEGHao）。

その後、ユーザーをドキュメントサイト（例：https://xxxxx.apidog.io）にリダイレクトし、トークンをauth_tokenというクエリパラメータとして含めます：

Apidogはトークンを自動的に検証します。成功すれば、ユーザーはドキュメントの内容にアクセスできます。

ログインフローは以下の図に示されています：

重要な注意事項

JWTはバックエンドで生成され、Apidogで設定されたシークレットを使用して署名されなければなりません。

JWTはauth_token URLパラメータを介してドキュメントサイトに戻される必要があります。

Apidogはトークンを自動的に解析し、検証します。

ドキュメントサイトのURLは、Apidogが提供するデフォルトのアドレスまたは設定したカスタムドメインのいずれかです。

FAQ

ログインページにはどの技術スタックを使用できますか？

制限はありません。バックエンドがPOSTログインリクエストを処理し、auth_tokenを含むURLを返すことができれば機能します。Node.js、PHP、Python、Goなど、すべてサポートされています。

サンプルプロジェクトはありますか？

公開範囲

デフォルトでは、ドキュメントの公開範囲はすべてのSharedリソースに設定されている。これをAPIsで設定できるよ。詳細は可視性設定を参照してね。

リリース

APIドキュメントの複数のバージョンを作成して公開できる。APIバージョンの公開についてもっと学ぶ。

release settings for API Documentations.jpg

ドメイン

Apidog提供のドメイン: ドキュメントにはデフォルトでApidogのサブドメインが付与される。例えば、https://vhh2uhkjv7.apidog.ioのようにね。手動で変更することもできる。すべてのApidogドキュメントはapidog.ioドメインを使用しているよ。

カスタムドメイン: Apidogドキュメントを自分のドメインにバインドできる。カスタムドメインについてもっと学ぶ。

domain settings for API documentations.jpg

カスタマイズ

APIドキュメントの外観やレイアウトをカスタマイズできるよ。

customize appearance and layouts for API documentation.png

外観

基本情報

Basic Infoに切り替えて、APIドキュメントのさまざまな基本オプションを設定できるよ。例えば：

タイトル

ロゴ

ファビコン

メインカラー

言語

ライト/ダークモード

コンテンツ表示

content display for API documentation.png

Content displayでは、APIドキュメントに表示するフィールドをカスタマイズできるよ。例えば：

ベースURL

オーナー

エンドポイント説明の上に「最終更新」時間を表示

ドキュメントの最後に「最終更新」時間を表示

リクエストサンプル

OperationId

高度な設定

ユーザーにアクセスさせたくない情報を隠すことができるよ。例えば：

「Powered by Apidog」を隠す（プロフェッショナルプラン以上で利用可能）

「Run in Apidog」ボタンを隠す（プロフェッショナルプラン以上で利用可能）

「Try it out」ボタンを表示

「Export」や「Clone」データを許可

レイアウトとナビゲーション

ページレイアウトを簡単にカスタマイズできる。カスタムレイアウトについてもっと学ぶ。

高度な設定

ドキュメント検索

公開されたAPIドキュメントにはデフォルトで組み込みの検索機能があるけど、ApidogはAlgoliaとの統合で検索機能を強化できる。ドキュメント検索についてもっと学ぶ。

CORSプロキシ

ブラウザのセキュリティ制限による問題を避けるために、CORSプロキシを指定できる。CORSプロキシについてもっと学ぶ。

Google analytics

ApidogのドキュメントサイトはGoogle analyticsとの統合をサポートしている。Google AnalyticsとDoc Sitesの連携についてもっと学ぶ。

API Hubへの公開

API Hubにドキュメントを公開することもできる。これはApidogが運営するオープンプラットフォームで、APIの共有と探索に特化しているよ。

説明

プロジェクトがAPI Hubに公開されている場合、この説明がAPI Hubに表示されるよ。

「Export」や「Clone」データを許可

メインブランチでリリースされたドキュメントデータをエクスポートできる。

ドキュメントリダイレクトルール

URLが変更されたときにユーザーを正しいドキュメントに自動的にリダイレクトするルールを設定できる。これによりリンク切れを防ぎ、シームレスな体験を提供できるよ。

URL & Slugルール

APIドキュメントのURLルールを定義できる。

複数のドキュメントサイトを公開する

同じプロジェクト内で異なるチャネルにドキュメントを公開するために、公開中に追加のドキュメントサイトを作成できる。管理を簡単にするために、メインサイトの設定を各新しいサイトに複製できるよ。各サブサイトには独自のカスタムドメイン名を持たせることもできる。

サブサイトのみが公開されたドキュメントの可視性範囲を設定でき、どのリソースが公開されるかを選択できる。

ドキュメントサイトの公開