API仕様をコードとして扱うとは？意味とメリット

API契約は、おそらく同時に3つの場所に存在しています。Wikiの図、誰かが前四半期にエクスポートしたPostmanコレクション、そして2リリース前に稼働中のサービスから乖離してしまった手書きのMarkdownドキュメント。これら3つが食い違うとき、チームは推測するしかありません。推測はインテグレーションを破綻させます。

API仕様をコードとして扱うことで、この問題は解決します。1つのOpenAPIファイルを書き、Gitにコミットし、他のソースファイルと同じようにレビューします。その単一のファイルから、モック、テスト、ドキュメント、SDKを生成します。仕様は後回しにされるものではなくなり、誰もがそれに従って構築する契約となります。

このガイドでは、Spec-as-Codeとは何か、なぜOpenAPIファイルがアプリケーションコードと同じ厳密さを持つべきなのか、そしてツールと格闘することなくワークフローを実行する方法を説明します。

button

Spec-as-Codeとは何か

Spec-as-Codeとは、API定義がバージョン管理下に置かれたプレーンテキストファイルであることを意味します。データベースのレコードでも、共有リンク付きのホストされたドキュメントでもありません。`git diff`、ブランチ、マージが可能なファイルです。

この考え方は、ドキュメントが記述対象のコードと同じリポジトリに置かれ、同じパイプラインを通じて出荷されるDocs-as-Codeから直接借用しています。Spec-as-Codeは、API契約自体にも同じ規律を適用します。OpenAPIドキュメント（YAMLまたはJSON）が成果物であり、それ以外のすべてはそこから生成されます。

この変化には、一つの大きな結果が伴います。仕様は唯一の真実の情報源となるのです。開発者が`/users/{id}`が何を返すかを知りたいとき、古くなったWikiページではなく仕様を読みます。QAがテストを作成するとき、仕様に対してアサートします。パートナーが統合するとき、仕様から生成されたSDKを利用します。一つのファイルから、多くの出力が得られるのです。

なぜ仕様をコードのように扱うのか

一度仕様がGit内のファイルになれば、ソースコードに対して既に信頼しているあらゆるワークフローを継承できます。

プルリクエストでのレビュー。エンドポイントへの変更はPRの差分として表示されます。レビュー担当者は、どのフィールドが変更されたか、どのステータスコードが追加されたか、レスポンスの形式が後方互換性を損ねるかどうかを正確に確認できます。破壊的変更はもはや本番環境でのサプライズではなく、マージ前のコメントスレッドになります。これがGitネイティブAPIワークフローの核です。

差分に優しいフォーマット。プレーンなYAMLはきれいに差分が表示されます。5行の変更を数秒で読み解くことができます。バイナリのエクスポートや、何が変わったかが見えないホスト型ツールと比較してみてください。Gitに仕様があれば、`blame`、履歴、差分がすべて機能します。

真のバージョン管理。すべての変更にはコミット、著者、タイムスタンプがあります。リリースにタグを付けたり、`v2`の再設計のためにブランチを切ったり、悪い変更を1つのコマンドでロールバックしたりできます。APIの履歴は監査可能になります。タグ付けとブランチ戦略の詳細については、GitでのOpenAPIバージョン管理をご覧ください。

唯一の真実の情報源。モック、テスト、ドキュメントはすべて同じファイルから派生するため、個別に乖離することはありません。仕様を更新し、再生成すれば、すべての出力が一貫性を保ちます。

ここで、2つのアプローチが実際にどのように比較されるかを示します。

懸念事項	ホスト型ツールでの仕様	コードとしてのAPI仕様
変更レビュー	手動、見落としやすい	PR差分、ブロックするレビュー
履歴	制限されるかベンダーロックされる	完全なGitログ
ロールバック	多くの場合手動	`git revert`
真実の情報源	曖昧	コミットされたファイル
CI統合	後付け	ネイティブ

成果物としてのOpenAPI

OpenAPIは広くサポートされており、機械可読であるため、仕様にとって明白なフォーマットです。リポジトリに保管するOpenAPI 3.1ファイルの小さくも完全な一部です。

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
 format: uuid
 responses:
 "200":
 description: The requested order
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"
 "404":
 description: Order not found
components:
 schemas:
 Order:
 type: object
 required: [id, status, total]
 properties:
 id:
 type: string
 format: uuid
 status:
 type: string
 enum: [pending, shipped, delivered]
 total:
 type: number
 format: float

このファイルが契約です。`Order`にフィールドを追加すると、差分は1行です。`status`列挙型を変更すると、レビュー担当者は即座にそれを確認できます。`api/openapi.yaml`の下、サービスコードの隣に置いておけば、仕様は記述対象の実装と共に移動します。

仕様とドキュメント

単一のソースファイルの利点は、そこから生成されるすべてのものです。

モック。モックサーバーを仕様に合わせることで、1つのエンドポイントも構築される前に実行可能なAPIが得られます。フロントエンドチームやモバイルチームは初日から契約に対する統合を開始します。仕様が変更されると、モックもそれに合わせて変更されます。

テスト。稼働中のサービスが仕様と一致することを主張する契約テストを生成します。デプロイされたエンドポイントが仕様で宣言されていないフィールドを返した場合、テストは失敗します。これにより、顧客が気付く前に契約と実行中のコード間の乖離を捉えることができます。

ドキュメント。仕様を自動的に参照ドキュメントとしてレンダリングします。もう誰もエンドポイントのテーブルを手書きすることはありません。ドキュメントは仕様と一致します。なぜなら、それらはレンダリングされた仕様そのものだからです。

SDK。同じファイルから複数の言語でクライアントライブラリを生成します。パートナーは常に現在の契約を反映した型付きSDKを受け取ります。

各出力は仕様の関数です。入力を変更し、出力を再生成すれば、一貫性は自動的に保たれます。

Apidogが仕様を唯一の真実の情報源にする方法

Spec-as-Codeを手動で実行するということは、CLI、モックサーバー、ドキュメントジェネレーター、Gitフックを組み合わせることを意味します。Apidogはそれを一つのワークフローに集約します。

ApidogのSpec-Firstモードは、OpenAPIファイルを権威ある定義として扱います。仕様に沿ってエンドポイントを設計し、Apidogはモック、テスト、ドキュメントをそれに完全に同期させます。

これを実用的にするのが双方向Git同期です。ApidogはリポジトリからOpenAPIファイルを読み込み、変更を書き戻すことができるため、Git内のファイルとApidog内のプロジェクトは常に一致します。視覚的な設計が速い場合は視覚的に、YAMLの直接編集が速い場合は直接編集し、どちらのパスも同じコミットされたファイルに反映されます。これにより、チームに豊富なエディタを提供しながら、PRレビューフローを維持できます。仕様変更をアップストリームにプッシュするメカニズムについては、GitHubにOpenAPI仕様を同期する方法をご覧ください。

結果として：OpenAPIファイルは唯一の真実の情報源であり続け、視覚的なツールはその上に位置し、それを置き換えるものではありません。

よくある落とし穴

Spec-as-Codeはシンプルですが、いくつかの落とし穴がチームを早期に捉えます。

仕様と実装間の乖離。仕様を書くだけでは十分ではありません。稼働中のサービスがそれに一致するかどうかを何もチェックしなければ、両者は静かに乖離します。CIに契約テストを追加して、不一致があればビルドが失敗するようにし、顧客ではなくビルドで問題を捕捉するようにします。

生成されたものと手書きのものの混同。仕様がコードアノテーションから生成されるのか、それともソースとして手書きされるのかを決定します。両方を混ぜると、どちらが権威ある部分なのか誰もわからないファイルになってしまいます。どちらか一方の方向を選んでください。仕様が真実の情報源である場合、コードアノテーションはそれに対してチェックするものであり、第二のマスターコピーではないと扱います。

仕様を契約ではなくドキュメントとして扱うこと。読むだけの仕様はドキュメントです。モック、テスト、SDKを生成する仕様は契約です。価値はファイルが存在することからではなく、出力を連携させることから生まれます。

レビューのスキップ。レビューなしでマージされるGit内の仕様は、単なるGit内のファイルに過ぎません。重要なのはプルリクエストです。コードと同じように、仕様の変更にもレビューを義務付けてください。

始め方

Spec-as-Codeは段階的に導入できます。

仕様をコミットする。OpenAPIファイルを`api/openapi.yaml`のような既知のパスにリポジトリに移動させます。
PRレビューを必須にする。仕様変更がコードと同じレビューゲートを通過するようにします。差分が議論の中心となります。
1つの出力を生成する。モックまたはドキュメントから始めます。仕様をジェネレーターに接続し、ファイルが更新されたときに出力も更新されるようにします。
CIチェックを追加する。すべてのPRで仕様をリンティングします。マージ前に無効なOpenAPIを捕捉します。
契約テストでループを閉じる。モックとドキュメントが流動的になったら、稼働中のサービスが仕様と一致することを主張するテストを追加します。

各ステップはそれ自体で完結しています。ステップ1で価値を得られ、追加ごとにそれが増幅されます。

この変化は説明するには小さく、効果は大きいです。Git内の1つのファイルをコードのようにレビューし、すべてのダウンストリームを生成します。視覚的な編集とGit同期を組み込みたい場合は、ApidogのSpec-Firstモードをお試しください。OpenAPIファイルが唯一の真実の情報源であり続けます。

よくある質問

「API Spec as Code」は「Docs-as-Code」と同じですか？

両者は同じ哲学を共有しています。成果物をバージョン管理下に置き、通常のパイプラインを通じて出荷するということです。Docs-as-Codeはドキュメントに適用され、Spec-as-CodeはAPI契約自体に適用されます。実際には、コミットされた仕様から生成されたドキュメントは定義上Docs-as-Codeであるため、両者は互いに補強し合います。

仕様ファイルはどのようなフォーマットを使用すべきですか？

YAML形式のOpenAPIが一般的な選択肢です。YAMLはプルリクエストで差分がきれいに表示され、人間が読みやすい一方で、モック、テスト、SDKの生成のために機械が解析可能です。JSONも機能しますが、YAMLの方がより整理された差分を生成する傾向があります。

仕様が実際のAPIから乖離するのをどう防ぎますか？

稼働中のサービスがコミットされた仕様と一致することを主張する契約テストをCIに追加します。エンドポイントが宣言されていないフィールドを返したり、文書化されたフィールドを削除したりした場合、ビルドは失敗します。このフィードバックループこそが、仕様を希望的なドキュメントから強制力のある契約へと変えるものです。