あなたのコードはGitにあります。CIパイプライン、レビュー、リリース履歴もGitにあります。それなのに、なぜあなたのAPI仕様書は別の場所にあるのでしょうか？
GitネイティブなAPIワークフローでは、OpenAPI定義がコードと同じ場所に保持されます。仕様書をプレーンなYAMLまたはJSONファイルとして編集し、コミットし、他のすべてに使うのと同じレビュープロセスを通してプッシュします。個別のクラウドデータベースは不要です。エクスポート・インポートの手間もありません。仕様書はリポジトリ内の単なる別のファイルに過ぎません。
GitネイティブなAPIワークフローとは
GitネイティブなAPIワークフローは、API仕様書をコードとして扱います。OpenAPIファイルはサービスとともにリポジトリに置かれます。すべての変更はコミットです。すべてのコミットには、作成者、メッセージ、差分があります。
これにより、ソースコードに期待する3つのことが得られます。
- バージョン履歴。誰がいつエンドポイントを変更したかを確認できます。
git blameは仕様書にも機能します。 - ブランチングとレビュー。仕様書の変更はプルリクエストを通して行われます。レビュー担当者は、マージされる前に正確な差分を確認できます。
- 単一の真実の源。
mainにあるファイルが契約です。ツール、ドキュメント、モックはすべてそこから読み取ります。
これが、Spec-First APIワークフローの核となる考え方です。仕様が先行し、実装がそれに続きます。この実践について深く知るには、Spec-First API開発に関するガイドをご覧ください。
対照的なアプローチは、独自のクラウドアプリ内に仕様書を保存することです。これはチームが成長したり、プロセスが成熟するまでは機能しますが、その後は問題が生じます。
クラウドにロックされたAPI仕様書の問題点
ほとんどのAPI設計ツールは、独自のデータベースに仕様書を保持しています。あなたは彼らのUIを通して編集します。あなたが所有していると思っている「ファイル」は、実際には他人のシステム内の1行に過ぎません。
これは予測可能な形で破綻します。
レビューが2ヶ所で行われる。コードの変更はGitHubを通して行われます。仕様書の変更は、独自のコメントと履歴を持つ別のツールを通して行われます。レビュー担当者はコンテキストを切り替えなければならず、承認は同期されなくなります。
差分が隠される。仕様書がクラウドデータベースにある場合、プルリクエストで明確な行ごとの差分を確認できません。何が実際に変更されたのか分からないまま、「デザインのv3」を承認することになります。
エクスポートが面倒になる。仕様書をCIに取り込むには、エクスポートして、そのエクスポートをコミットし、その間に誰もクラウドのコピーを編集していないことを願うしかありません。2つの真実の源、避けられない1つの競合。
自動化が妨げられる。リンター、契約テスト、コードジェネレーターはディスク上のファイルを必要とします。クラウドにロックされた仕様書は、それらの実行前にフェッチステップを強制します。
API仕様書をコードとして扱うことで、これらすべてが解消されます。ファイルが仕様書であり、Gitが履歴です。既存のパイプラインが残りの処理を行います。この原則については、API仕様書をコードとして扱うで詳しく説明しています。
Apidog Spec-Firstモードの仕組み
Spec-Firstモードは、すでにコミットとブランチで考えているチーム向けに構築されています。APIを生のYAMLまたはJSONファイルとして設計し、ApidogはこれらのファイルをGitリポジトリと双方向で同期します。
得られるものは次のとおりです。
IDEスタイルのOpenAPIエディタ
仕様書はフォームではなく、コードエディタで記述します。このエディタには、IDEに期待される利便性が備わっています。
- YAMLとJSONのシンタックスハイライト。
- OpenAPIおよびSwaggerスキーマに対する検証機能により、入力中に間違いが明らかになります。
- OpenAPIキーワード、型、参照のオートコンプリート。
あなたはファイルの正確な内容を管理できます。隠されたフィールドやUI専用のメタデータはありません。
生のYAML/JSONファイル
仕様書は実際のファイルです。その一部を以下に示します。
openapi: 3.1.0
info:
title: Orders API
version: 1.2.0
paths:
/orders/{orderId}:
get:
summary: Get an order by ID
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
"200":
description: Order found
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"404":
description: Order not found
components:
schemas:
Order:
type: object
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
これがリポジトリに格納されるファイルです。あなたが編集したものがコミットされます。
自動解析されるナビゲーション可能なアウトライン
入力すると、Apidogはファイルを解析し、左サイドバーに視覚的なアウトラインを構築します。パス、操作、スキーマがクリック可能なツリーとして表示されます。これにより、設計ツールの読みやすさと生ファイルの正確さを同時に得ることができます。
長い仕様書もナビゲート可能です。何百行もスクロールすることなく、特定のエンドポイントにジャンプできます。
双方向Git同期
Spec-FirstモードはGitプロバイダーに接続し、変更を双方向で同期します。GitHubとGitLabを直接サポートし、Git接続を介してAzure DevOpsもサポートします。
チームメイトがプッシュした変更を取り込みます。Apidogエディタでローカルに編集します。その後、同じブランチにコミットしてプッシュします。リポジトリとワークスペースは常に同期されます。
コミット、プッシュ、同期ステータスインジケーター
Gitを管理するためにApidogを離れる必要はありません。変更をステージし、コミットメッセージを書き、プッシュします。同期ステータスインジケーターが現在の状況を知らせます。プッシュが成功すると、「たった今同期されました」のように表示されます。プッシュする前に気が変わった場合は、未プッシュの編集を破棄して、最後に同期された状態に戻すことができます。
この双方向同期は、GitネイティブAPIワークフローの核心です。GitHub側の詳細な手順については、OpenAPI仕様書をGitHubに同期するをご覧ください。
セットアップのウォークスルー
空のリポジトリから同期された仕様書への移行方法を説明します。完全なリファレンスはSpec-Firstモードのドキュメントにあります。
- リポジトリからプロジェクトを作成します。Apidogで新しいSpec-Firstプロジェクトを開始し、Gitプロバイダーを接続します。API仕様書を保持するリポジトリを選択し、追跡するブランチ（通常は
main）を選択します。Apidogは既存の仕様書ファイルをエディタにプルします。
- 仕様書を編集します。エディタでOpenAPIファイルを開きます。エンドポイントを追加したり、スキーマを調整したり、レスポンスを修正したりします。入力中にシンタックスハイライト、検証、オートコンプリートがガイドします。ファイルが変更されると、左サイドバーのアウトラインが更新されます。
- 変更、追加、削除されたファイルを追跡します。Apidogは、前回の同期以降に変更したファイルを表示します。変更、追加、削除されたファイルにはフラグが立てられ、コミットに何が含まれるかを正確に把握できます。
- コミットメッセージを記述します。どのGitクライアントでも行うのと同じように、変更を平易な言葉で説明します。「getOrderに404レスポンスを追加」は、「仕様書を更新」よりも優れています。
- プッシュします。追跡対象のブランチにコミットを送信します。これでチームメイトとCIパイプラインは新しいバージョンを確認できます。
- 「たった今同期されました」を確認します。同期ステータスインジケーターがプッシュを確認するのを見てください。「たった今同期されました」と表示されたら、ローカルの編集とリモートブランチが一致しています。ここから、変更は通常のプルリクエストとレビュープロセスを通して流れていきます。
これが完全なループです：プル、編集、コミット、プッシュ、検証。エクスポートの手順は不要です。第二の真実の源もありません。
Spec-Firstモード vs Design-Firstモード
Apidogは2つの作業方法をサポートしています。違いは、仕様書がどこに存在し、どのように編集するかです。
| Spec-Firstモード（ベータ版） | Design-Firstモード | |
|---|---|---|
| 仕様書の保存場所 | Git内の生のYAML/JSONファイル | Apidogクラウドプロジェクト |
| 主要エディタ | IDEスタイルのコードエディタ | ビジュアルなフォームベースUI |
| バージョン管理 | ネイティブGit（コミット、ブランチ、差分） | Apidogの履歴とブランチ |
| 双方向Git同期 | あり（GitHub、GitLab、Azure DevOps） | エクスポート/インポート経由 |
| 最適な用途 | Gitを中心に作業するチーム | ビジュアルなワークフローを好むチーム |
どちらのモードも「優れている」というわけではありません。それぞれ異なる習慣に対応します。レビューおよびリリースプロセスがすでにGitで実行されている場合、Spec-Firstモードはそのギャップを解消します。チームが視覚的に設計し、生のOpenAPIにほとんど触れない場合は、Design-Firstモードの方が適しているかもしれません。
いつ使用するか
Spec-Firstモードは次の場合に使用します。
- 仕様書がプルリクエストとコードレビューを経るべきである場合。
- API契約に対して
git blameと実際のコミット履歴が必要な場合。 - CIがディスク上のファイルを必要とする仕様書のリンティング、契約テスト、コード生成を実行する場合。
- 複数のエンジニアが仕様書を編集し、クリーンでマージ可能な差分が必要な場合。
- あるツールから別のツールへエクスポートする手間を省きたい場合。
チームが生のOpenAPIを記述せずにAPIを設計する場合、または非エンジニアが仕様書を所有し、フォームベースのエディタを好む場合は、ビジュアルでクラウドファーストのアプローチを継続してください。
よくある質問
GitネイティブAPIワークフローとは何ですか？
GitネイティブAPIワークフローは、OpenAPI仕様書をGitリポジトリ内のファイルとして保存し、コミット、ブランチ、プルリクエストを通してすべての変更を管理します。仕様書はアプリケーションコードと同じレビューおよびバージョン管理プロセスに従うため、単一の真実の源となります。
Apidog Spec-FirstモードはGitHubとGitLabをサポートしていますか？
はい。Spec-FirstモードはGitHubとGitLabと直接双方向同期します。Azure DevOpsはGit接続を介してサポートされています。リポジトリを接続し、ブランチを選択すると、Apidogがあなたの編集とリモートを同期状態に保ちます。
OpenAPIファイルを生のYAMLまたはJSONとして編集できますか？
はい。Spec-Firstモードは、生のYAMLおよびJSON用のIDEスタイルエディタを提供し、シンタックスハイライト、スキーマ検証、OpenAPIおよびSwaggerのオートコンプリート機能を備えています。左サイドバーのアウトラインはファイルを自動解析するため、大規模な仕様書でも素早くナビゲートできます。
Spec-FirstモードとDesign-Firstモードの違いは何ですか？
Spec-Firstモードは、仕様書をGit内のファイルとして保持し、双方向同期を備えたコードエディタで編集します。Design-Firstモードは、視覚的なフォームベースのエディタを備えたApidogクラウドプロジェクトに仕様書を保持します。ワークフローがすでにGitで実行されている場合はSpec-Firstを選択してください。
結論
GitネイティブAPIワークフローは、コードとAPI契約の間の分離を終わらせます。仕様書はファイルになり、ファイルはコミットになり、そのコミットはすでに信頼しているレビュープロセスを経て流れていきます。
Apidog Spec-Firstモードは、IDEスタイルのエディタ、ナビゲーション可能なアウトライン、双方向Git同期を提供し、それを実現します。生のYAMLまたはJSONを編集し、明確なメッセージをコミットし、プッシュすると、「たった今同期されました」というステータスが表示されます。
Spec-Firstモードを試して、あなたのAPI仕様書をGitに持ち帰りましょう。