アピドッグのスペックファーストモードとは？

Apidog Spec-Firstモードは、OpenAPI仕様をソースコードとして扱うチーム向けに構築されたベータ版ワークスペースです。IDEスタイルのエディタでYAMLまたはJSONとして直接仕様を記述し、接続されたGitリポジトリと双方向で同期します。フォームベースのエディタがユーザーとファイルの間に入ることはありません。仕様がプロジェクトそのものです。APIツールを離れることなく、実際のコードエディタでopenapi.yamlを編集し、GitHubにプッシュしたいと思ったことがあるなら、このモードが最適です。

このガイドは、その機能の完全なリファレンスです。すべての機能、完全なセットアップ手順、対象ユーザー、ベータ版で予想される制限、および実用的なFAQを網羅しています。このアプローチのより広範な考え方については、当社のGitネイティブAPIワークフローをご覧ください。

Apidog Spec-Firstモードとは？

Spec-Firstモードは、Apidogのベータ版編集モードで、APIデザインが生のOpenAPIドキュメントとして存在します。ファイルを開き、YAMLまたはJSONを編集し、検証し、コミットしてGitにプッシュします。Apidogは仕様とリポジトリを双方向で同期させます。チームメイトの変更をプルするとエディタが更新され、自分の編集をプッシュするとリポジトリが更新されます。

これは、特定の種類のチーム向けに構築されています。すでにネイティブGitワークフローを実行している人々、つまりバックエンドエンジニア、プラットフォームチーム、プルリクエストで契約をバージョン管理するAPIファーストの企業にとって、このモードは自然に感じられるでしょう。仕様ファイルは唯一の信頼できる情報源となり、Gitは他のコードベースと同様に履歴、レビュー、ブランチングを処理します。

これは、ほとんどのAPIツールの動作とは異なります。ほとんどのツールは、グラフィカルなフォームの裏に仕様を隠します。Spec-Firstモードはファイルそのものを表示します。

Spec-Firstモード vs Design-Firstモード：概要

Apidogには2つのモードがあります。Design-Firstモードは、ほとんどのチームが最初に使い始める視覚的でフォームベースのエディタです。Spec-Firstモードは、このガイドで説明するコードエディタのアプローチです。以下に簡単な説明をします。トレードオフの完全な内訳については、当社のSpec-First vs Design-First比較をお読みください。

側面	Design-Firstモード	Spec-Firstモード (ベータ)
主要エディタ	ビジュアルフォームとUIパネル	生のYAML/JSONコードエディタ
信頼できる情報源	Apidogプロジェクトデータベース	Gitリポジトリ内の仕様ファイル
Git同期	エクスポート/インポートベース	ネイティブな双方向同期
最適	ビジュアルデザイナー、混合チーム	Gitネイティブなエンジニアリングチーム
学習曲線	緩やかでガイド付き	OpenAPIを知っていれば馴染みやすい

どちらのモードも「優れている」わけではありません。それぞれ異なるチームにサービスを提供します。モード間は切り替え可能であり、これについては後述します。

主要機能

Spec-Firstモードは単なるテキストボックスではありません。エディタ、ナビゲーター、Git統合、チームコントロールがバンドルされています。ここでは、すべての機能を詳しく説明します。

IDEスタイルのOpenAPIエディタ

ワークスペースの中心は、OpenAPIドキュメント用のフルコードエディタです。生のYAMLまたはJSONを直接編集します。これは、普段から使っているエディタのように動作します。

キー、値、構造を色付けするシンタックスハイライトにより、大規模なファイルでも読みやすさを維持できます。入力中にOpenAPI仕様に対してエラーを検出するスキーマ検証機能があり、不正なレスポンスオブジェクトや必須フィールドの欠落がすぐに表示されます。OpenAPIとSwaggerに特化したオートコンプリート機能により、記述中に有効なキーワード、フィールド名、構造が提案されます。

このオートコンプリートは、スキーマの奥深くに入り込み、「additionalPropertiesだったかadditionalItemsだったか」思い出せない場合に最も重要になります。エディタは仕様を知っているので、正確さを保つのに役立ちます。

編集する内容の小さな例：

paths:
 /users/{userId}:
 get:
 summary: Get a user by ID
 operationId: getUserById
 parameters:
 - name: userId
 in: path
 required: true
 schema:
 type: string
 responses:
 '200':
 description: A single user
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/User'

自動解析されるナビゲーション可能なアウトライン

生の仕様ファイルはあっという間に長くなります。実際のAPIは数千行になることもあります。Spec-Firstモードは、ファイルを視覚的なアウトラインに自動解析する左サイドバーでこれを解決します。

入力するにつれて、Apidogはドキュメントを読み取り、パス、操作、スキーマ、コンポーネントなどのナビゲーション可能な構造を構築します。アウトラインの任意のノードをクリックすると、エディタはファイル内のその場所にジャンプします。スクロールではなく、意味によってナビゲートします。アウトラインは仕様の変更に合わせてライブで更新されるため、常にファイル内の内容を反映しています。

これにより、大規模なopenapi.yamlも管理しやすくなります。「1,847行目」ではなく、「POST /orders操作」という観点で考えられます。

双方向Git同期

これがこのモードの核となる機能です。Spec-FirstモードはGitリポジトリに接続し、仕様を双方向で同期します。

GitHubとGitLabは直接サポートされています。Azure DevOpsは汎用Git接続を介して機能し、標準のGitクレデンシャルを使用してApidogをリポジトリにポイントできます。接続されると、プルすることでリポジトリの変更がエディタに取り込まれ、プッシュすることで編集がリポジトリに送り返されます。Gitが共有の基盤であるため、仕様はチーム全員で一貫性が保たれます。

プロバイダー	接続方法
GitHub	直接統合
GitLab	直接統合
Azure DevOps	汎用Git接続経由

特定のプロバイダーに焦点を当てたステップバイステップの手順が必要な場合は、当社のOpenAPI仕様をGitHubに同期するガイドでその具体的なフローを説明しています。

コミット、プッシュ、および同期ステータスインジケーター

単に保存して「うまくいけばいい」というわけではありません。Spec-Firstモードは、すでに知っているGitモデルに従います。編集が完了したら、コミットメッセージを記述して変更をコミットします。次に、それを接続されたリポジトリにプッシュします。

同期ステータスインジケーターは、常に状況を知らせてくれます。ローカルの仕様がリポジトリと一致している場合は「Synced just now」（今すぐ同期済み）のような状態を表示し、未プッシュの作業がある場合は変化します。目の前のバージョンがチームメイトが見ているバージョンであるかどうかを常に把握できます。推測することなく、古い仕様もありません。

ファイル変更の追跡

コミットする前に、Spec-Firstモードは正確な変更内容を表示します。ファイルレベルでの変更を追跡し、各エントリを修正、追加、または削除としてマークします。Gitのステータス出力を確認するように、変更のセットをレビューします。

これはチェックポイントを与えるため重要です。正しい編集のみをコミットし、余分なものがないことを確認できます。そして、実験がうまくいかなかったと判断した場合、未プッシュの編集をリポジトリに到達する前に破棄することができます。これにより、共有履歴をクリーンに保ちます。ローカルでの探索は、プッシュを選択するまでローカルに留まります。

ブランチおよびリポジトリスコープのプロジェクトとチーム権限

Spec-Firstプロジェクトは抽象的なものではありません。特定のレポジトリと特定のブランチ（通常はmain）から作成されます。このスコープ設定は、プロジェクトが常にGit内の実際の場所を指すことを意味します。あなたの仕様、履歴、ブランチが一致します。

チームの権限はセットアップ時に設定されます。誰がプロジェクトにアクセスできるか、何ができるかを決定するため、契約を扱う人々はあなたが意図した人々になります。プロジェクトがレポジトリとブランチに紐付けられているため、アクセスモデルはすでにGitで強制しているアクセスモデルを反映できます。

Spec-Firstモードのセットアップ方法

セットアップは短く、直線的なフローです。以下の手順に従ってください。公式のウォークスルーは、スクリーンショット付きでdocs.apidog.com/spec-first-mode-beta-2058268m0にあります。

モードを切り替えます。ApidogのAPIモジュールを開き、モジュールの左下にあるモードトグルを見つけて、Design-FirstからSpec-Firstモードに切り替えます。
Gitプロバイダーを接続します。GitHubまたはGitLabを直接認証します。Azure DevOpsの場合、Gitクレデンシャルを使用して汎用Git接続を設定します。
リポジトリからプロジェクトを作成します。仕様を保持するリポジトリを選択し、ブランチ（通常はmain）を選択します。Apidogは新しいプロジェクトをそのリポジトリとブランチにスコープします。
チームの権限を設定します。セットアップ中に、誰がプロジェクトにアクセスできるか、何を変更できるかを設定します。
仕様を編集します。IDEスタイルのエディタでopenapi.yamlまたはopenapi.jsonを開きます。左側のアウトラインを使用してナビゲートします。記述中に検証とオートコンプリートを活用します。
変更をコミットします。明確なコミットメッセージを記述します。最初に追跡された変更を確認します。保持したくないものは破棄します。
リポジトリにプッシュします。コミットを接続されたブランチにプッシュします。
同期を確認します。同期ステータスインジケーターを確認します。「Synced just now」（今すぐ同期済み）と表示されていれば、仕様とリポジトリが一致しています。

これが一連のループです。切り替え、接続、作成、編集、コミット、プッシュ、検証。

一般的な日々のワークフロー

セットアップ後のモードの実際の使用感は以下の通りです。

一日の始まりには、接続されたブランチから最新の状態をプルし、エディタにチームメイトが昨晩マージした変更が反映されるようにします。アウトラインを開き、作業中の操作をクリックして、YAMLの編集を開始します。新しいエンドポイントにはリクエストボディが必要なので、スキーマを定義します。オートコンプリートがフィールド名を正しく入力するのに役立ち、検証機能が$refのタイプミスが問題になる前に検出します。

エンドポイントが問題なく見えたら、ファイル変更追跡を確認します。自分の修正が表示されます。コミットメッセージに「Add POST /invoices endpoint」のように記述し、コミットしてプッシュします。ステータスインジケーターが「Synced just now」に切り替わります。仕様は他のすべてと同様にGitに存在するため、チームメイトは通常のプルリクエストで変更をレビューします。

そのフローで追加する内容の例は次のとおりです。

components:
 schemas:
 Invoice:
 type: object
 required: [id, amount, currency]
 properties:
 id:
 type: string
 format: uuid
 amount:
 type: integer
 description: Amount in the smallest currency unit
 currency:
 type: string
 example: USD
 status:
 type: string
 enum: [draft, sent, paid]

すべてのサイクルは信頼できるツール内で完結します。仕様はコードであり、コードとして扱われます。

Spec-Firstモードは誰が使うべきか

Spec-Firstモードは、他のチームよりも一部のチームに合っています。自分がどちらに当てはまるか正直に考えてみてください。

チームがすでにGitを使用している場合は、Spec-Firstモードを使用してください。プルリクエストでAPI契約をレビューする場合、サービスコードの隣で仕様をバージョン管理したい場合、またはエンジニアがYAMLを直接編集することを好む場合、このモードは摩擦を減らします。OpenAPIドキュメントを第一級の成果物として扱うバックエンドチームやプラットフォームチームに強く適しています。

ガイド付きのビジュアルエクスペリエンスを望む場合は、代わりにDesign-Firstモードを選択してください。非エンジニアがデザインに貢献するチーム、またはYAMLを記述するよりもフォームをクリックする方を好む人にとっては、そちらの方が早く作業が進むでしょう。プロダクトとデザインがエンドポイントについて意見を出し合う混合チームは、視覚エディタを好むことが多いです。間違いというものはありません。チームが実際にどのように機能するかと一致するモードを選択してください。この決定については、当社の比較記事で詳しく説明しています。

制限事項とベータ版に関する注意点

Spec-Firstモードはベータ版です。この言葉は実際の意味を持つため、それに応じて期待値を設定してください。

ベータ版であるため、機能はまだ成熟段階にあります。Apidogがフィードバックに基づいてモードを改善するにつれて、機能や動作が変更される可能性があります。今日の直接プロバイダー統合はGitHubとGitLabをカバーしていますが、Azure DevOpsは専用の統合ではなく汎用Git接続に依存しています。チームが特定のGitプロバイダーまたはワークフローに依存している場合は、重要なプロジェクトをこのモードにコミットする前に、それがニーズに合致するかどうかを確認してください。

仕様はライブリポジトリと同期するため、通常のGitの規律が適用されます。慎重にコミットし、意図的にプッシュし、編集が必要ない場合は破棄オプションを使用してください。ファイル変更追跡と同期インジケーターは安全を保つために存在しますが、クリーンな履歴に対する責任は依然としてあなたにあります。ベータ版は、メインブランチに影響を与える新しいツールと同様に扱ってください。まず非重要なリポジトリで試してから、フローを信頼できるようになったら拡張してください。

ベータ版の利点は影響力です。初期のフィードバックが機能の方向性を形成するため、ワークフローに不足しているものがあれば、報告する価値があります。

FAQ

Spec-Firstモードは無料ですか？

Spec-FirstモードはApidogのベータ機能です。アクセスはApidogプランに従うため、現在のプランとベータステータスに対してモードの利用可能性を確認してください。ベータ版であるため、最も簡単な方法はAPIモジュールで有効にし、アカウントで利用可能かどうかを確認することです。

どのGitプロバイダーがサポートされていますか？

GitHubとGitLabは直接統合によってサポートされています。Azure DevOpsは汎用Git接続を介して機能し、標準のGitクレデンシャルを使用してApidogをリポジトリに接続します。他のGitホストも、プロバイダー固有のAPIではなく標準のGitに依存するため、その汎用接続を介して機能する可能性があります。

Design-Firstモードに戻すことはできますか？

はい、できます。モード切り替えはAPIモジュールの左下隅にあり、そこでSpec-FirstとDesign-Firstを切り替えることができます。ロックインされることはありません。目の前のプロジェクトに合ったモードを選択してください。

どのファイル形式を編集できますか？

IDEスタイルのエディタで、OpenAPIドキュメントを生のYAMLまたはJSONとして編集します。エディタは、OpenAPIとSwaggerの両方でシンタックスハイライト、スキーマ検証、オートコンプリートを提供するため、どちらの形式で記述しても正確さを保つことができます。

未プッシュの編集はどうなりますか？

未プッシュの編集は、プッシュするまでローカルに保存されます。Spec-Firstモードはすべての変更を修正、追加、削除として追跡し、同期インジケーターは未プッシュの作業があることを示します。変更を取り消すことにした場合、プッシュする前に破棄すれば、共有履歴には一切入りません。

結論

Apidog Spec-Firstモードは、OpenAPIエディタとGitを一体化させます。仕様をYAMLまたはJSONとして編集し、自動解析されたアウトラインでナビゲートし、入力しながら検証し、GitHub、GitLab、またはAzure DevOpsと双方向で同期します。コミットメッセージ、プッシュ、変更追跡、明確な同期インジケーターにより、すでに知っているGitワークフローをAPI契約に適用できます。

これはベータ版であり、仕様をソースコードと見なしたいGitネイティブチーム向けです。もしあなたがそうであるなら、このモードは真剣に検討する価値があります。APIモジュールで有効にし、リポジトリを接続し、小さな編集・コミット・プッシュサイクルを試してそのフローを実感してください。準備ができたら、ドキュメントでSpec-Firstモードを試して、信頼できるリポジトリに接続してください。

button