Spec-first Mode（ベータ）

Spec-first Mode は、API 仕様ファイルを信頼できる唯一の情報源としたいチーム向けのモードです。このモードでは、OpenAPI または Swagger ファイルを Apidog 内で直接設計・保守し、編集しながら生成される API ドキュメントをプレビューし、ファイルを Git と同期できます。

チームがすでに YAML または JSON の仕様ファイルを使用している場合、Git を通じて API の変更をレビューしている場合、または API 設計をコードリポジトリのワークフローに自然に組み込みたい場合は、Spec-first Mode を使用します。

Spec-first Mode の仕組み

通常の Apidog プロジェクトでは、API は一般的にビジュアルフォームを通じて作成・編集されます。Spec-first プロジェクトでは、主なワークスペースはファイルベースです。

次のようなファイルを扱います。

openapi.yaml

openapi.json

Swagger 2.0 ファイル

Markdown ファイルおよびその他の補助プロジェクトファイル

Apidog は仕様ファイルを解析し、ナビゲーション可能な API 構造に変換します。生ファイルの編集、対応するビジュアルフォームの使用、仕様の検証、生成ドキュメントのプレビュー、変更の Git へのプッシュを行うことができます。

Spec-first プロジェクトを作成する

+ New Project をクリックします。

プロジェクトタイプのセレクターで Spec-first Mode を選択します。

GitHub、GitLab、Azure DevOps、Bitbucket などの Git プロバイダーに接続します。

組織またはワークスペースを選択し、既存のリポジトリを選択するか、オプションが利用可能な場合は新しいリポジトリを作成します。

Apidog が同期するメインブランチを選択します。

webhook をインストールするかどうかを選択します。

webhook をインストールすると、Git リポジトリへのプッシュによって自動同期をトリガーできます。通常、これにはリポジトリの管理者権限が必要です。管理者権限がない場合は、webhook のインストールをスキップして手動で同期できます。

プロジェクト名を入力し、メンバー権限を設定して、Create をクリックします。

作成後、Apidog は最初の同期を実行します。リポジトリのデフォルトブランチが main でない場合、Apidog はリポジトリのブランチ名をプロジェクトのメインブランチとして使用します。

Spec-first プロジェクトにはサンプルプロジェクトデータは含まれません。API コンテンツは仕様ファイルから取得されます。

Specs ワークスペース

Spec-first プロジェクトには、左サイドバーに Specs ワークスペースが含まれます。ここは、仕様ファイルと Git 同期を管理する主な場所です。

このワークスペースには、主に次の 3 つの領域があります。

ファイルエクスプローラー: 同期されたリポジトリのファイルとフォルダーを参照および管理します。

API 構造ツリー: 概要、エンドポイント、スキーマ、定義など、解析された OpenAPI コンテンツをナビゲートします。

エディター: コードビューでファイルを編集します。また、対応している OpenAPI ノードについてはフォームビューで編集します。

構造ツリーでエンドポイント、スキーマ、またはその他の対応ノードを選択すると、Apidog はソースファイルの関連部分を開きます。これにより、Specs ワークスペースを離れることなく、ファイルレベルのビューと API レベルのビューを行き来できます。

仕様ファイルを編集する

エディターは、さまざまなファイルタイプと編集モードに対応しています。

コードビュー

YAML、JSON、Markdown、その他のテキストファイルを直接編集するには、Code ビューを使用します。これは Spec-first Mode で作業する際のデフォルトの方法です。

フォームビュー

対応している OpenAPI ノードについては、Apidog は Form ビューも提供します。これにより、基盤となる仕様ファイルを信頼できる唯一の情報源として維持しながら、構造化されたコントロールを通じて一般的な API フィールドを編集できます。

フォームビューは、次のような対応ノードで利用できます。

API 概要

エンドポイント

スキーマ

定義

選択したファイルまたはノードをフォームビューで編集できない場合、Apidog はコードビューのままにします。

編集中に検証とプレビューを行う

Spec-first Mode には、エディターヘッダーに検証ツールとプレビューツールが含まれています。

検証

Validation パネルには、現在の仕様で検出された問題が表示されます。これには警告とエラーが含まれます。検証バッジには、検出された問題の合計数が表示されます。

変更をコミットする前に、このパネルを使用して構文の問題、必須フィールドの欠落、ルール違反を見つけます。

プレビュー

Preview パネルには、選択した仕様ノードが生成される API ドキュメントでどのように表示されるかが示されます。

プレビューは次に対して利用できます。

API 概要

エンドポイント

スキーマ

定義

エンドポイントの場合、Preview には次が含まれます。

Docs: 生成されたエンドポイントドキュメントです。

Try it out: 選択したエンドポイント定義に基づいてリクエストを送信するためのリクエストパネルです。

スキーマ、定義、および概要ノードの場合、Preview には生成されたドキュメントビューが表示されます。

Validation と Preview は同じサイドパネルを使用します。一方を開くと、もう一方は閉じます。

Git から変更を同期する

他のチームメンバーが接続済みリポジトリに変更をプッシュした場合、最新のファイルを Apidog にプルできます。

Specs ワークスペースを開きます。

Specs サイドバーで現在のブランチ名をクリックします。

Git Pull をクリックします。

webhook 同期がインストールされている場合、Apidog は Git プロバイダーからプッシュイベントを受信し、自動的に同期をトリガーすることもできます。

変更を Git にコミットしてプッシュする

Apidog でファイルを編集した後、変更を接続済みリポジトリにプッシュします。

Specs ワークスペースで 1 つ以上のファイルを編集します。

Changes をクリックして、変更、追加、名前変更、削除されたファイルを確認します。

Commit & Push をクリックします。

Push to Git repo モーダルで、含めたいファイルを選択します。

コミットメッセージを入力します。

Push をクリックします。

ローカル編集を保持したくない場合は、プッシュする前に Discard all changes を使用します。

ブランチを管理する

Spec-first Mode は、ブランチベースのコラボレーションに対応しています。Apidog は同期された Git ブランチをプロジェクトブランチにマッピングするため、仕様のバージョン間を切り替えることができます。

ブランチを切り替える

Specs サイドバーでブランチ名をクリックし、ドロップダウンから別のブランチを選択します。

既存の Git ブランチを追跡する

Git にブランチが存在するものの Apidog にインポートされていない場合は、Import New Branch をクリックし、ブランチを選択してインポートします。その後、Apidog はそのブランチの追跡と同期を開始します。

ブランチを作成する

Project Settings > Git & Branches を開き、New Branch をクリックして、既存のプロジェクトブランチからブランチを作成します。

ブランチを再同期する

ブランチ同期に失敗した場合、またはファイルが古く見える場合は、Project Settings > Git & Branches の Re-sync を使用します。これにより、そのブランチの同期状態がリセットされ、ファイルが再度インポートされます。

同期ログを表示する

同期に失敗した場合は、ブランチアクションを開き、View Logs を選択して同期の詳細を確認します。

ブランチの追跡を停止または削除する

追跡中のブランチを削除すると、Apidog の同期設定からそのブランチが削除されます。メイン以外のブランチについては、プロジェクトブランチレコードも削除できます。

Webhook 同期と権限

webhook 同期は任意ですが、リポジトリへのプッシュに合わせて Apidog を最新の状態に保ちたいチームには推奨されます。

webhook 同期が有効な場合:

Apidog は接続済み Git プロバイダーに webhook を登録します。

対応しているプッシュイベントのみが処理されます。

Apidog は同期前に webhook の署名またはトークンを検証します。

権限要件:

webhook のインストールには通常、リポジトリの管理者権限が必要です。

変更のプッシュには書き込み権限が必要です。

webhook のインストールをスキップした場合でも、手動同期は引き続き利用できます。

プロジェクト作成時に webhook のインストールをスキップした場合は、後で Project Settings > Git & Branches からインストールできます。

ストレージ backed の Spec-first プロジェクト

一部の Spec-first プロジェクトでは、外部 Git リポジトリの代わりに Apidog の内部ストレージを使用する場合があります。

これらのプロジェクトでも、Specs ワークスペース、ファイルベースの編集、検証、プレビュー、ブランチ管理を使用します。

UI ラベルは少し異なります。

Git Pull は Sync と表示されます。

Commit & Push は Save と表示されます。

Git プロバイダー情報と外部 webhook 設定は非表示になります。

注意事項と制限

Spec-first Mode は現在ベータ版です。

Specs ワークスペースは Spec-first プロジェクトにのみ表示されます。

Spec-first プロジェクトはサンプル API データを作成しません。

仕様ファイルは 信頼できる唯一の情報源 です。変更は Specs ワークスペースを通じて行うか、Git を通じて同期する必要があります。

十分なリポジトリ権限がない場合、webhook のインストールに失敗することがあります。書き込みアクセス権がある場合は、手動同期を引き続き使用できます。

Spec-first Mode（ベータ）

Spec-first Mode の仕組み#

Spec-first プロジェクトを作成する#

Specs ワークスペース#

仕様ファイルを編集する#

コードビュー#

フォームビュー#

編集中に検証とプレビューを行う#

検証#

プレビュー#

Git から変更を同期する#

変更を Git にコミットしてプッシュする#

ブランチを管理する#

ブランチを切り替える#

既存の Git ブランチを追跡する#

ブランチを作成する#

ブランチを再同期する#

同期ログを表示する#

ブランチの追跡を停止または削除する#

Webhook 同期と権限#

ストレージ backed の Spec-first プロジェクト#

注意事項と制限#