私がこれまで関わってきたAPIチームには、だいたい2つの運用パターンがありました。
1つ目は、OpenAPI仕様を手で書き、specs/ ディレクトリにコミットし、Gitを唯一の信頼できる情報源として扱うチームです。2つ目は、ビジュアルデザイナーで仕様を作り、CIで問題が出たタイミングで仕様をエクスポートし、UI上の定義とリポジトリ上の定義の差分を後から修正するチームです。
どちらの運用も経験しました。前者は初動が遅い一方で、90日後には速くなります。後者はその逆です。Apidogは長く後者寄りのツールでした。ビジュアルデザイナーは使いやすいものの、YAMLとの往復変換はコードレビューで説明が必要な運用になりがちでした。
しかし4月中旬、新規プロジェクト作成画面にスペックファーストモード（ベータ）が追加されました。ローンチ直後ではなく、実際のサイドプロジェクトのOpenAPI仕様で半日ほど試してから判断しました。この記事では、チームで導入する前に確認すべきポイント、セットアップ手順、向いているケースと向いていないケースを整理します。
スペックファーストモードで変わること
Apidogには現在、性質の異なる2つのプロジェクトモードがあります。
デフォルトの一般モードでは、「+ 新規プロジェクト」からプロジェクトを作成し、フォルダーとフォームベースのUIでエンドポイントを定義します。OpenAPI仕様は内部的に生成されます。YAMLに慣れていないチームや、非エンジニアもAPI定義に関わるチームには引き続き有効です。
一方、スペックファーストモードでは、中心になるのはフォームではなく、実際の .yaml / .json ファイルです。Gitリポジトリとの双方向同期があり、OpenAPI仕様そのものをディスク上のファイルとして扱います。
主な違いは次の通りです。
-
.yaml/.jsonを直接編集する - OpenAPIスキーマに基づく補完が使える
- 構文ハイライトがある
- 入力中にパス一覧がサイドバーへ反映される
- Gitリポジトリと双方向同期できる
- UIは仕様ファイルのラッパーではなく、仕様ファイルを見るためのビューになる
特に重要なのは、リアルタイムのアウトライン表示です。YAMLの問題は「難しい」ことよりも、構造が長いファイルの中に埋もれやすいことです。Apidogのスペックファーストモードでは、ファイルを直接編集しながら、左側のアウトラインでエンドポイントを移動できます。
スペックファースト開発の本質は、テキストエディタが好きかどうかではありません。成果物をどこで管理するかです。スペックファーストモードでは、リポジトリ内のOpenAPIファイルが成果物になります。ApidogのUIは、そのファイルを編集・確認するための作業環境です。
セットアップ手順
実際に試したセットアップ手順は次の通りです。Git認証を含めても、10分程度で完了しました。
1. スペックファーストモードでプロジェクトを作成する
プロジェクト画面から、次の順に進みます。
+ 新規プロジェクト
→ 一般
→ スペックファーストモード
注意点として、一般モードには「推奨」ラベルが付いています。普段どおりにプロジェクトを作ると、スペックファーストモードのタイルを見落としやすいです。OpenAPIファイルをGit中心で管理したい場合は、必ずスペックファーストモードを選びます。
2. Gitリポジトリに接続する
次に、Gitリポジトリと接続 セクションでGitプロバイダーを認証します。
設定する項目は次の3つです。
Organization
Repository
Main branch
私はGitHubで試しました。選択したブランチ内の .yaml / .json ファイルが、Apidog側の作業対象として同期されます。
3. プロジェクト名と権限を設定する
続いて、次を設定します。
Project Name
Team permissions
作成すると、初回同期が走り、リポジトリ内のOpenAPI仕様ファイルがApidogのワークスペースに取り込まれます。
4. OpenAPI仕様をファイルとして編集する
同期後、任意のYAMLファイルを開きます。ここでは、フォームではなく実ファイルを編集します。
たとえば、次のようなOpenAPI定義をそのまま編集できます。
openapi: 3.0.3
info:
title: Pet Store API
version: 1.0.0
paths:
/pets:
get:
summary: List pets
responses:
'200':
description: A list of pets
編集中は、OpenAPIスキーマに基づく補完が効きます。さらに、paths に追加したエンドポイントはサイドバーのアウトラインに反映されます。アウトライン上のエンドポイントをクリックすると、該当する行へ移動できます。
VS CodeでOpenAPI拡張を使っている人には近い操作感ですが、Apidogではエンドポイント一覧や同期状態も同じ画面で確認できます。
5. 変更をコミットしてプッシュする
変更後は、右上の Commit & Push をクリックします。
ダイアログには次の要素があります。
- 変更されたファイル一覧
- コミットメッセージ入力欄
PushDiscard all changesCancel
個別にステージングするステップはありません。変更一覧に含まれるものがコミット対象になります。仕様ファイル中心の編集であれば、この簡略化は十分実用的です。
6. 同期インジケーターを確認する
左下に同期状態が表示されます。
図では Synced just now と表示されています。これは、Apidog上の編集内容とリモートリポジトリの状態が一致していることを示します。
実運用では、次のように確認するとわかりやすいです。
Synced just now → 同期済み
Changes available → リモート側に変更あり
Changes pending → ローカル側に未プッシュ変更あり
インジケーターが緑であれば、Apidogとリポジトリは一致しています。複数人で編集する場合は、この表示を常に確認するのがよさそうです。
使ってわかった実装上のポイント
半日使って、特に重要だと感じた点は3つあります。
1. アウトラインの更新が速い
過去に使ったライブOpenAPIエディタの多くは、保存時に再解析する仕組みでした。そのため、エンドポイントを追加してからサイドバーに表示されるまでに遅延がありました。
Apidogのスペックファーストモードでは、入力中にアウトラインが更新されます。ほぼ即時に反映されるため、アウトラインを「確認用」ではなく「ナビゲーション用」として使えます。
長いOpenAPIファイルを扱う場合、この差は大きいです。
2. Git同期は実際に双方向で動く
Apidogを開いたまま、ローカルクローン側で同じ仕様ファイルを編集し、ターミナルからプッシュしてみました。
git add openapi.yaml
git commit -m "Update pet schema"
git push origin main
Apidog側ではリモート変更が検知され、同期インジケーターが変化しました。その後、ワンクリックで変更をエディターに取り込めました。
つまり、チーム内で次のような混在運用ができます。
- 一部のメンバーはApidogで編集する
- 一部のメンバーはVS CodeやVimで編集する
- どちらも同じGitリポジトリ上のOpenAPIファイルを編集する
重要なのは、Apidog内の状態とGit内の状態を別々に管理しなくてよいことです。
3. 同じプロジェクト内で一般モードには戻れない
スペックファーストモードで作成したプロジェクトは、スペックファースト用のプロジェクトになります。途中で一般モードのビジュアルデザイナーへ切り替えることはできません。
これは、内部のデータモデルが異なるためです。
もし同じ仕様を両方の操作方法で扱いたい場合は、次のような運用になります。
Gitリポジトリ
├── OpenAPI仕様ファイル
│
├── Apidog スペックファーストプロジェクト
│ └── Git同期で編集
│
└── Apidog 一般モードプロジェクト
└── 同じ仕様からインポート
完全にシームレスではありませんが、Git上の仕様を中心に据えれば運用は可能です。
向いているチーム
スペックファーストモードが特に向いているのは、次のようなチームです。
- OpenAPI仕様をすでに手書きしている
- OpenAPI仕様をGitでレビューしたい
-
spectral lintなどをCIで実行している - 仕様からSDKや型定義を生成している
- Pull Request上でAPI変更をレビューしたい
- Apidog上の仕様とリポジトリ上の仕様のズレをなくしたい
- エンジニアがVS CodeやVimでも編集できる状態を保ちたい
たとえば、CIで次のようなチェックをしている場合には相性がよいです。
name: OpenAPI Lint
on:
pull_request:
paths:
- "specs/**/*.yaml"
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install -g @stoplight/spectral-cli
- run: spectral lint specs/openapi.yaml
この場合、Apidogで編集した仕様も通常のGitフローに乗ります。レビュー、CI、生成処理をすべて同じファイルに対して実行できます。
向いていないチーム
一方で、次のようなチームには一般モードのほうが向いています。
- OpenAPIをほとんど書いたことがない
- YAMLを直接編集するメンバーが少ない
- 非エンジニアがフォームUIでAPI定義を作る必要がある
- ビジュアルデザイナーが参加の前提になっている
- 同じプロジェクト内でフォーム編集とファイル編集を切り替えたい
スペックファーストモードは、オンボーディングの簡単さよりも、仕様ファイルの忠実性を優先するモードです。APIスペシャリスト以外のメンバーが多いチームでは、一般モードのほうが導入しやすいです。
また、同じプロジェクト内で一般モードとスペックファーストモードを混在させたい場合も、現時点では向いていません。この点はベータ版らしい制約です。
導入する場合のおすすめワークフロー
チームで試すなら、いきなり全APIを移行するより、1つの仕様ファイルから始めるのが安全です。
おすすめの流れは次の通りです。
1. 既存のOpenAPI仕様をGitに置く
2. CIでlintを設定する
3. Apidogでスペックファーストプロジェクトを作成する
4. Gitリポジトリを接続する
5. 小さなエンドポイント変更をApidog上で行う
6. Commit & Pushする
7. Pull RequestとCIで差分を確認する
8. チームメンバーに編集手順を共有する
最初に確認すべき観点は次の3つです。
- Apidog上の編集差分が期待通りGitに出るか
- CIのOpenAPI lintが通るか
- ローカルエディタで編集した変更をApidogが取り込めるか
この3点が問題なければ、日常的な仕様編集には十分使えます。
まとめ
これまでスペックファースト開発は、APIデザインツールを諦めることとほぼ同義でした。YAMLで作業してGitを信頼する代わりに、モックサーバーやテストランナーとの統合を諦める。あるいは、ビジュアルデザイナーを使う代わりに、Gitを唯一の情報源にすることを諦める。そのどちらかでした。
Apidogのスペックファーストモードでは、この分断がかなり小さくなっています。
リポジトリ内のファイルが、エディター内のファイルです。アウトラインは状態ではなくビューです。Git同期はエクスポート機能ではなく、作業フローの一部です。
新規プロジェクト作成時にスペックファーストモードを選び、既存のGitリポジトリを接続すれば、最初のコミットまでは10分程度で到達できます。継続利用するかどうかは、1週間ほど実際のAPI変更で試せば判断できます。
Top comments (0)