ほとんどのAPI設計チュートリアルは、マウスから始まります。ビジュアルエディタを開き、スキーマをキャンバスにドラッグし、ダイアログをクリックしてフィールドを追加します。それは機能しますが、多くのチームが実際にデプロイする方法には合いません。API定義がGitに存在し、プルリクエストでレビューされ、CIを通過する場合、デプロイと同じ方法で設計したいものです。つまり、ターミナルから、テキストで、スクリプト可能なコマンドを使ってです。
コマンドラインからAPIを設計するということは、シェルを離れることなく、コントラクトを作成し、スタイルガイドに対してリンティングし、単一のファイルにバンドルし、スタブを生成することを意味します。すべてのステップは再現可能です。すべてのステップはパイプラインで実行できます。AIエージェントやチームメイトがあなたのセットアップを再現する必要がある場合、彼らはあなたがクリックしたボタンを推測するのではなく、あなたが行ったのと同じコマンドを実行します。
このガイドでは、2つのアプローチを紹介します。まず、単一目的のツールで構築された一般的なオープンソースのパスです。OpenAPIファイルを作成し、Spectralでリンティングし、Redocly CLIでバンドルし、openapi-generatorでサーバスタブを生成します。次に、設計、スキーマ、エンドポイント、認証がすべて1つのプロジェクトに存在し、ターミナルから操作できるApidog CLIのパスです。まず、より深い概念的背景を知りたい場合は、「APIの設計方法」に関するガイドと「REST APIの設計」に関するウォークスルーをお読みください。
Apidogに沿って進める場合は、まずバイナリを入手してください。「Apidog CLIインストールガイド」では、npm install -g apidog-cliステップとapidog login --with-tokenハンドシェイクについて説明しており、「完全なApidog CLIガイド」ではすべてのコマンドグループが網羅されています。
一般的なオープンソースのルート：作成、リンティング、バンドル、生成
古典的なCLI設計スタックは、複数の独立したツールを連携させることで構成されます。API定義はバージョン管理下のOpenAPIファイルに保持し、各ツールをステップとして実行します。これがGitネイティブAPI設計ワークフローであり、これは本当に優れたものです。その概要は次のとおりです。
OpenAPIドキュメントの作成
まずプレーンなYAMLファイルから始めます。特別なエディタは必要ありません。どのテキストエディタでも動作します。最小限のopenapi.yamlは次のようになります。
openapi: 3.0.3
info:
title: Orders API
version: 1.0.0
paths:
/orders/{orderId}:
get:
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: An order
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
components:
schemas:
Order:
type: object
required: [id, status]
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
APIが成長するにつれて、それを複数のファイルに分割し、$refで参照します。これにより、各スキーマは独立して読みやすく、レビュー可能になります。
Spectralによるリンティング
手書きのOpenAPIは乖離しがちです。誰かがoperationIdを忘れたり、別の人がレスポンスを文書化しなかったり、また別の人が独自の命名規則を考案したりします。リンターは、レビュー前にこれらのすべてを捕捉します。StoplightのSpectralが標準的な選択肢です。これはOpenAPI用のルールセットを提供し、独自のルールを作成することもできます。
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
Spectralはすべての違反を行番号と深刻度とともに表示します。CIで終了コードをチェックすることで、エラー時にビルドを失敗させることができます。代替案が必要な場合は、RedoclyのCLIとvacuumも同じ役割を果たします。vacuumは高速で、Spectral互換のリンターとして機能します。どれを選択するかにかかわらず、重要な点は、リンティングは独立した専用のツールであり、独自のステップとして実行するということです。
Redocly CLIによるバンドル
定義が複数のファイルに分割されると、ほとんどの下流ツールは単一の自己完結型ドキュメントを求めます。Redocly CLIはすべての$refを解決し、ツリーを1つのファイルに平坦化します。
npm install -g @redocly/cli
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Redoclyはリンティング（redocly lint）とドキュメントのプレビューも行うため、一部のチームではスタイルチェックとバンドルの両方にこれを使用しています。その公式ドキュメントには、すべてのコマンドセットが記載されています。
openapi-generatorによるスタブの生成
クリーンでバンドルされた仕様があれば、コードを生成できます。openapi-generatorはOpenAPIドキュメントを、数十の言語に対応するサーバスタブ、クライアントSDKなどに変換します。
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
-i dist/openapi.bundled.yaml \
-g spring \
-o ./server
-g springを-g python-flask、-g go-server、またはサポートされている任意のジェネレータと交換します。これで、契約に正確に一致するスキャフォールディングが得られます。
これがオープンなルートの全体像です。4つのツール、4つのコマンド、すべてスクリプト可能です。コストは配線です。ファイルレイアウト、リンター設定、バンドルステップ、ジェネレータ設定を自分で維持し、各ツールには独自の慣習があります。最大限の制御を望み、接着剤（ツール間の連携）を気にしない場合にうまく機能します。
Apidog CLIのルート：1つのプロジェクトでの設計
もう一つのアプローチでは、設計、スキーマ、エンドポイント、モック、認証を、ターミナルから操作する単一のプロジェクト内に保持します。apidog-cliバイナリは、単なるテストランナーではなく、完全なプロジェクトリソースCLIです。データモデル用のschema、操作用のendpoint、組織化用のfolder、認証用のsecurity-schemeに加えて、import、export、mockなど、設計全体のコマンドグループを備えています。
まず正直に言っておきますが、ApidogはOpenAPIのリンティングを行ったり、スタイルガイドを強制したりしません。それが目的ではありません。リンティングが必要な場合は、パイプラインにSpectralまたはvacuumを維持してください。Apidogはオープンソースでもありません。無料枠のある商用製品です。Apidogが提供するのは、設計の各要素を自分でつなぎ合わせる必要がない統合されたプロジェクトです。「API設計とテストのためのSwaggerの代替案」では、このトレードオフがどこで理にかなっているかを解説しています。
まずインストールと認証を行います（トークン設定についてはインストールガイドを参照してください）。
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
すべてのコマンドは構造化されたJSONを返し、ほとんどのレスポンスには、次に何を実行すべきか（あなたまたはエージェントに）を伝えるagentHints.nextStepsブロックが含まれています。任意のコマンドに--helpを追加すると、その正確なフラグを確認できます。
apidog schemaによるデータモデルの定義
設計はデータから始まります。再利用可能なOrderスキーマは、エンドポイントが参照する唯一の真の情報源となり、これは生のOpenAPIにおけるcomponents/schemasと同じ考え方ですが、プロジェクトリソースとして管理されます。
apidog schema --help
apidog schema create --project <PROJECT_ID>
出力はJSONなので、jqを通して新しいスキーマのIDを取得し、次のコマンドに渡すことができます。既存のOpenAPIファイルがある場合は、すべてを再入力するのではなく、インポートしてください。
apidog import --project <PROJECT_ID> --file openapi.yaml
apidog importはOpenAPI 3.x、Swagger 2.0、Postman、およびApidog形式を受け入れるため、既存の定義をワンステップでライブプロジェクトにできます。
apidog endpointによるエンドポイントの定義
モデルが配置されたら、操作を追加します。endpointグループは、エンドポイントを作成および更新し、定義したスキーマやそれらを整理するフォルダに接続します。
apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
エンドポイントをJSONとして一覧表示すること自体が有用です。複数のブランチ間で出力を比較したり、すべてのパスに期待するレスポンスがあるかをチェックするスクリプトに渡したりできます。関連するエンドポイントをfolderコマンドでグループ化することで、プロジェクトが成長してもナビゲートしやすく保てます。
apidog security-schemeによる認証の定義
認証は契約の一部であり、後付けではありません。security-schemeグループは、クライアントがどのように認証するかを定義します。APIキー、ベアラー・トークン、OAuth 2.0などです。これはOpenAPIのcomponents/securitySchemesにマッピングされるため、インポートとエクスポートがクリーンに往復します。
apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
プロジェクトレベルで一度スキームを定義することで、各操作が独自の認証を再宣言する代わりに、すべてのエンドポイントがそれを参照できるようになります。それは、リンターがそうでなければあなたに文句を言うであろう一貫性そのものです。
apidog cli-schema validateによる書き込みの検証
変更をコミットしたり、プロジェクトをCIに渡したりする前に、リソース定義が適切に形成されていることを確認したいものです。CLIには、CLIが期待するスキーマに対して定義ファイルをチェックするcli-schema validateコマンドが付属しており、不正な書き込みがサイレントに適用されるのではなく、すぐに失敗するようになっています。
apidog cli-schema --help
apidog cli-schema validate --file resource.json
これをパイプラインのガードステップとして実行します。まず検証し、その後適用します。ゼロ以外の終了コードは、不正なリソースがプロジェクトに到達する前にパイプラインを停止させます。これはCLIの書き込みの検証であり、OpenAPIのスタイルリンティングではありません。これらは2つの異なるジョブであり、後者には引き続きSpectralが必要です。
OpenAPIへのエクスポート
Apidogで設計し、その後、標準的なアーティファクトを他のツールチェーンに渡します。apidog exportはOpenAPI、HTML、Markdown、またはPostman形式で出力します。
apidog export --project <PROJECT_ID> --format openapi -o dist/openapi.yaml
これで、移植可能なOpenAPIファイルに戻りました。それをSpectralに渡してリンティングを行ったり、openapi-generatorに渡してスタブを生成したり、ドキュメントビルドに組み込んだりできます。統合されたプロジェクトとオープンツールのスタックは排他的ではありません。エクスポートがそれらの間の橋渡しとなるため、行き詰まることはありません。
CIへの組み込み
すべてのコマンドには終了コードとテキスト出力があるため、どちらのルートもパイプラインでその真価を発揮します。最小限の設計チェックジョブでは、リンターを実行し、検証し、バンドルするという流れになるでしょう。
# fail on style violations
spectral lint openapi.yaml
# validate any CLI resource writes before applying
apidog cli-schema validate --file resource.json
# flatten to a single artifact for downstream steps
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Apidogの出力はagentHints.nextStepsを含むJSONであるため、このフローはAIコーディングエージェントからもきれいに実行されます。エージェントは構造化された結果を読み取り、推奨される次のステップを確認して実行します。GUIの画面スクレイピングは必要ありません。これがそもそもCLIから設計する理由のすべてです。人間が入力できるものは、スクリプトやエージェントも入力できるのです。
よくある落とし穴
分割されたファイルが下流ツールを壊す。 多数の$refファイルにまたがる定義は人間にとっては素晴らしいですが、ジェネレータにとっては扱いにくいものです。コードを生成したりドキュメントを公開したりする前に、常に単一のファイルにバンドルしてください。redocly bundleがその解決策です。
Apidogがリンティングすると期待しても、それはしません。 Apidogはリソースを管理しますが、スタイルガイドを強制したり、OpenAPIの規則違反を指摘したりすることはありません。そのためには、Spectralまたはvacuumをパイプラインに含めてください。apidog cli-schema validateをリンターとして扱うのはよくある間違いです。それはリソースの構造を検証するのであって、OpenAPIのスタイルを検証するものではありません。
編集前にインポートを忘れる。 CLIを通じて既存のAPIを編集する場合、まず元の定義をプロジェクトにインポートしてください。空のプロジェクトを編集し、古いエンドポイントがそこにあると期待するのは、混乱を招く手っ取り早い方法です。
認証はエンドポイントごとに定義するのではなく、一度定義する。 プロジェクトレベルでsecurity-schemeを定義し、それを参照してください。すべての操作で認証を再宣言すると、契約が乖離する原因となります。
まとめ
CLIからAPIを設計することで、クリック操作の多いタスクが繰り返し可能なコマンドセットに変わります。オープンなルート（作成、Spectralでのリンティング、Redoclyでのバンドル、openapi-generatorでの生成）は、完全な制御とロックインなしを提供します。Apidog CLIルートは、スキーマ、エンドポイント、認証が一体となった統合プロジェクトを提供し、すべてのコマンドがエージェント対応のJSONを返します。エクスポートが両者の橋渡しとなるため、行き詰まることはありません。
あなたのチームに合ったルートを選んでください。すでにGitに多くの単一目的ツールがある場合は、それらを維持し、移植可能なアーティファクトが必要なときにapidog exportを追加してください。もし、接着剤（ツール間の連携）の維持に煩わされたくない場合は、Apidogをダウンロードし、CLIをインストールして、マウスに触れることなく次のAPIを設計してください。