DEV Community

Cover image for CLIからAPIを設計する方法
Akira
Akira

Posted on • Originally published at apidog.com

CLIからAPIを設計する方法

ほとんどのAPI設計チュートリアルは、ビジュアルエディタを開いてスキーマをドラッグ＆ドロップするところから始まります。しかし、API定義をGitで管理し、プルリクエストでレビューし、CIで検証してデプロイするチームには、テキストとコマンドで完結する設計フローのほうが適しています。APIコントラクトの作成、検証、バンドル、コード生成をターミナルから実行できれば、すべての手順を再現・自動化できます。

今すぐApidogを試す

コマンドラインベースのAPI設計では、シェルを離れずに次の作業を行います。

  1. OpenAPIコントラクトを作成する
  2. スタイルガイドに沿ってリンティングする
  3. 複数ファイルの定義を単一ファイルへバンドルする
  4. サーバースタブやSDKを生成する
  5. CIで同じ手順を実行する

本記事では、次の2つの実装パスを扱います。

  • オープンソースのCLIスタック：OpenAPI、Spectral、Redocly CLI、openapi-generatorを組み合わせる
  • Apidog CLI：スキーマ、エンドポイント、認証を単一プロジェクトとしてCLIから管理する

API設計の基本を先に確認したい場合は、APIの設計方法およびREST APIの設計も参照してください。

Apidog CLIを使う場合は、最初にCLIをインストールして認証します。Apidog CLIインストールガイドでは、npm install -g apidog-cli と apidog login --with-token の手順を説明しています。完全なApidog CLIガイドでは、利用可能なコマンドグループを確認できます。

一般的なオープンソースのルート：作成、リンティング、バンドル、生成

オープンソースのCLIスタックでは、API定義をGit管理し、用途別のツールを順番に実行します。これはGitネイティブAPI設計ワークフローに適した構成です。

基本的なパイプラインは次のとおりです。

OpenAPIを作成
  ↓
Spectralでリンティング
  ↓
Redocly CLIでバンドル
  ↓
openapi-generatorでコード生成
Enter fullscreen mode Exit fullscreen mode

1. OpenAPIドキュメントを作成する

まず、Git管理する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]
Enter fullscreen mode Exit fullscreen mode

APIが大きくなったら、スキーマやパスを複数ファイルに分割し、$refで参照します。

api/
├── openapi.yaml
├── paths/
│   └── orders.yaml
└── schemas/
    └── order.yaml
Enter fullscreen mode Exit fullscreen mode

この構成なら、変更範囲が小さくなり、プルリクエストでのレビューもしやすくなります。

2. Spectralでリンティングする

手書きのOpenAPIでは、operationIdの漏れ、レスポンス定義の不足、命名規則の不統一が発生しがちです。リンターをCIに組み込むと、レビュー前にこうした問題を検出できます。

Spectralをインストールします。

npm install -g @stoplight/spectral-cli
Enter fullscreen mode Exit fullscreen mode

OpenAPIファイルをリンティングします。

spectral lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Spectralは違反箇所を行番号と重要度付きで出力します。CIでは終了コードをそのまま利用し、違反時にジョブを失敗させられます。

spectral lint openapi.yaml || exit 1
Enter fullscreen mode Exit fullscreen mode

独自のルールセットを使う場合は、.spectral.yamlをリポジトリに追加します。

extends:
  - spectral:oas

rules:
  operation-operationId:
    severity: error
  info-contact:
    severity: warn
Enter fullscreen mode Exit fullscreen mode

代替ツールとしては、Redocly CLIやvacuumも利用できます。重要なのは、スタイル検証を独立したステップとして実行することです。

3. Redocly CLIでバンドルする

OpenAPI定義を複数ファイルに分割すると、コードジェネレータやドキュメントツールは単一ファイルの仕様を要求することがあります。その場合は、$refを解決したバンドル済みファイルを生成します。

npm install -g @redocly/cli
Enter fullscreen mode Exit fullscreen mode 
mkdir -p dist
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

生成されたdist/openapi.bundled.yamlは、下流のツールに渡す配布用アーティファクトとして扱えます。

Redocly CLIではリンティングも実行できます。

redocly lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

コマンドの詳細はRedocly CLI公式ドキュメントを参照してください。

4. openapi-generatorでサーバースタブを生成する

バンドル済みのOpenAPIファイルがあれば、サーバースタブやクライアントSDKを生成できます。

npm install -g @openapitools/openapi-generator-cli
Enter fullscreen mode Exit fullscreen mode

たとえばSpring向けのサーバースタブを生成する場合は、次のコマンドを実行します。

openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

ジェネレータは用途に応じて変更できます。

# Flaskサーバー
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g python-flask \
  -o ./server

# Goサーバー
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g go-server \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

このルートの利点は、各ツールを自由に置き換えられることです。一方で、ファイル構成、ルール設定、バンドル設定、生成設定を自分で保守する必要があります。

Apidog CLIのルート：1つのプロジェクトで設計する

もう1つの方法は、スキーマ、エンドポイント、認証、モックなどを単一のプロジェクトで管理することです。apidog-cliでは、API設計に関連するリソースをターミナルから操作できます。

主なコマンドグループは次のとおりです。

  • schema：データモデルの管理
  • endpoint：エンドポイントの管理
  • folder：エンドポイントの整理
  • security-scheme：認証スキームの管理
  • import：既存定義の取り込み
  • export：OpenAPIなどへの出力
  • mock：モック関連の操作

ApidogはOpenAPIのスタイルリンティングやスタイルガイド強制を目的としたツールではありません。OpenAPIの品質ルールを検査する場合は、Spectralまたはvacuumを併用してください。

Apidogはオープンソースではなく、無料枠のある商用製品です。その代わり、複数ツール間の設定や連携を減らし、設計リソースを統合プロジェクトで管理できます。API設計とテストのためのSwaggerの代替案では、この選択肢が適するケースを解説しています。

1. Apidog CLIをインストールして認証する 

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

トークンの設定手順はインストールガイドを参照してください。

各コマンドは構造化されたJSONを返します。多くのレスポンスには、次に実行する操作を示すagentHints.nextStepsが含まれます。

コマンドの詳細を確認するには、--helpを使います。

apidog --help
apidog schema --help
apidog endpoint --help
Enter fullscreen mode Exit fullscreen mode

2. apidog schemaでデータモデルを定義する

再利用可能なデータモデルを先に定義します。たとえばOrderスキーマを作成し、複数のエンドポイントから参照できるようにします。

apidog schema --help
apidog schema create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

CLI出力がJSONの場合、jqを使ってリソースIDを取り出し、後続処理に渡せます。

apidog schema create --project <PROJECT_ID> | jq -r '.data.id'
Enter fullscreen mode Exit fullscreen mode

既存のOpenAPI定義があるなら、手動で再入力せずにインポートします。

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

apidog importは、OpenAPI 3.x、Swagger 2.0、Postman、Apidog形式を受け入れます。既存のAPI定義をプロジェクトへ取り込む最初の操作として利用できます。

3. apidog endpointでエンドポイントを定義する

スキーマを用意したら、エンドポイントを追加します。

apidog endpoint --help
apidog endpoint list --project <PROJECT_ID>
apidog endpoint create --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

エンドポイントをJSONとして取得できるため、シェルスクリプトやCIからチェックできます。たとえば、エンドポイント一覧を保存してブランチ間で差分比較できます。

apidog endpoint list --project <PROJECT_ID> > endpoints.json
git diff -- endpoints.json
Enter fullscreen mode Exit fullscreen mode

関連するエンドポイントはfolderコマンドでグループ化します。APIが増えても、リソース構造を保ちやすくなります。

4. apidog security-schemeで認証を定義する

認証は後付けではなく、APIコントラクトの一部です。security-schemeを使って、APIキー、ベアラートークン、OAuth 2.0などの認証方式をプロジェクトレベルで定義します。

apidog security-scheme --help
apidog security-scheme list --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

プロジェクトレベルで認証スキームを定義すると、各エンドポイントで同じ認証設定を繰り返す必要がありません。OpenAPIのcomponents/securitySchemesと同じように、共通定義を参照する構成にできます。

5. apidog cli-schema validateで書き込みを検証する

リソース定義を適用する前に、CLIが期待する構造に従っているかを検証します。

apidog cli-schema --help
apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

CIでは、適用前のガードとして実行します。

apidog cli-schema validate --file resource.json || exit 1
Enter fullscreen mode Exit fullscreen mode

ここで検証するのはCLIリソースの構造です。OpenAPIの命名規則やスタイル違反を検出するものではありません。OpenAPIのスタイル検証には、引き続きSpectralやvacuumを使ってください。

6. OpenAPIへエクスポートする

Apidogで管理しているAPI設計を、他のツールチェーンで使うOpenAPIファイルとして出力できます。

mkdir -p dist

apidog export \
  --project <PROJECT_ID> \
  --format openapi \
  -o dist/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

エクスポート後は、通常のOpenAPIパイプラインに接続できます。

# OpenAPIスタイルを検証
spectral lint dist/openapi.yaml

# 配布用の単一ファイルへバンドル
redocly bundle dist/openapi.yaml -o dist/openapi.bundled.yaml

# サーバースタブを生成
openapi-generator-cli generate \
  -i dist/openapi.bundled.yaml \
  -g spring \
  -o ./server
Enter fullscreen mode Exit fullscreen mode

Apidogの統合プロジェクトとオープンソースのツールスタックは排他的ではありません。apidog exportを境界にして、両方を組み合わせられます。

CIへ組み込む

CLI設計の価値は、CIで同じ手順を実行したときに最大化されます。最小構成では、次の順序で実行します。

# 1. OpenAPIのスタイル違反を検出する
spectral lint openapi.yaml

# 2. CLIリソース定義を検証する
apidog cli-schema validate --file resource.json

# 3. 下流ツール向けに単一ファイルへバンドルする
mkdir -p dist
redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

GitHub Actionsでは、たとえば次のように設定できます。

name: Validate API Contract

on:
  pull_request:
    paths:
      - 'api/**'
      - '.spectral.yaml'

jobs:
  validate-api:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install CLI tools
        run: |
          npm install -g @stoplight/spectral-cli
          npm install -g @redocly/cli

      - name: Lint OpenAPI
        run: spectral lint api/openapi.yaml

      - name: Bundle OpenAPI
        run: |
          mkdir -p dist
          redocly bundle api/openapi.yaml -o dist/openapi.bundled.yaml

      - name: Upload bundled contract
        uses: actions/upload-artifact@v4
        with:
          name: openapi-contract
          path: dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog CLIの構造化JSON出力は、AIコーディングエージェントや自動化スクリプトにも適しています。GUIを画面スクレイピングする必要はなく、コマンド結果を読み取って次の操作を実行できます。

よくある落とし穴

分割したファイルをそのまま下流ツールへ渡す

多数の$refを含む定義は、人間には管理しやすくても、ジェネレータやドキュメントツールでは扱いにくいことがあります。コード生成や公開の前に、単一ファイルへバンドルしてください。

redocly bundle openapi.yaml -o dist/openapi.bundled.yaml
Enter fullscreen mode Exit fullscreen mode

ApidogをOpenAPIリンターとして扱う

Apidogはリソース管理とプロジェクト操作のためのCLIです。OpenAPIスタイルガイドの強制や規約違反の検出には、Spectralまたはvacuumを使用してください。

# OpenAPIのスタイル検証
spectral lint openapi.yaml

# CLIリソースの構造検証
apidog cli-schema validate --file resource.json
Enter fullscreen mode Exit fullscreen mode

この2つは別の責務です。

既存APIを編集する前にインポートしない

既存のOpenAPI定義をCLIで扱う場合は、最初にプロジェクトへ取り込みます。

apidog import --project <PROJECT_ID> --file openapi.yaml
Enter fullscreen mode Exit fullscreen mode

空のプロジェクトで編集を始めると、既存のエンドポイントやスキーマが存在する前提で操作してしまい、混乱の原因になります。

認証をエンドポイントごとに重複定義する

認証方式はプロジェクトレベルでsecurity-schemeとして定義し、各エンドポイントから参照する形にします。同じ認証設定を操作ごとに繰り返すと、設定の乖離が起こりやすくなります。

まとめ

CLIからAPIを設計すると、クリック操作に依存した作業を、再現可能なコマンドとCIパイプラインへ置き換えられます。

オープンソースのルートは、次のような構成です。

OpenAPI作成
→ Spectralでリンティング
→ Redoclyでバンドル
→ openapi-generatorで生成
Enter fullscreen mode Exit fullscreen mode

この方法は、最大限の制御とツール選択の自由を提供します。

一方、Apidog CLIでは、スキーマ、エンドポイント、認証を統合プロジェクトとして管理できます。さらに、OpenAPIへのエクスポートを通じてSpectral、Redocly、openapi-generatorなどの既存ツールとも連携できます。

すでにGit上で単一目的のツールを組み合わせているなら、そのパイプラインを維持しつつ、必要に応じてapidog exportを追加してください。ツール間の接続設定を減らし、統合されたプロジェクトとしてAPI設計を扱いたい場合は、Apidogをダウンロードし、CLIから次のAPIを設計してみてください。

Top comments (0)