メインコンテンツまでスキップ

設定

設定は CLI 引数 > 設定ファイル > 既定値 の優先順位で解決されます。結果は resolveConfig が返す CliConfig オブジェクトです。

CliConfig​

中心となる設定型です。specPath 以外はすべて省略可能です。

フィールド型既定値説明
specPathstring必須OpenAPI 3.2 JSON 仕様のパスまたは http(s):// URL
serverUrlstring（仕様から取得）仕様のサーバーベース URL を上書き
outputDirstring"./openapi-cli-report"レポートファイルの出力先ディレクトリ
formatsReportFormat[]["json","cli","html"]生成するレポート形式
filterFilterConfigundefinedテストする操作を絞り込む
concurrencynumber5最大同時リクエスト数。1～100 の整数
timeoutnumber30000リクエストごとのタイムアウト（ミリ秒）。1～600000 の整数。リモート仕様の取得にも適用
proxystringundefinedHTTP(S) プロキシ URL。例：http://proxy:8080
tlsTlsConfigundefinedTLS と証明書の設定
headersRecord<string, string>undefined各リクエストで送信する追加ヘッダー
authAuthConfigundefined認証設定
variablesRecord<string, string>undefined注入する Postman 変数 {{name}}
failOnErrorbooleantrueCLI のみ：テスト失敗後にゼロ以外の終了コードを返す。ライブラリの呼び出し側はレポートを確認する
envFilestringundefined1 行に 1 組の KEY=VALUE を記述した .env ファイルのパス
grpcReflectionboolean自動gRPC：明示的な設定、操作の拡張の順に優先。どちらもなければ proto パスが未指定の場合に有効
grpcProtoPathsstring[]undefinedgRPC：.proto ファイルまたはディレクトリのパス
mcpTransport"streamable-http" | "stdio""streamable-http"MCP：MCP 操作のトランスポート
mcpCommandstringundefinedMCP stdio：起動するコマンド
mcpArgsstring[]undefinedMCP stdio：コマンド引数
mcpCwdstringundefinedMCP stdio：作業ディレクトリ

ReportFormat は共用体型 "json" | "cli" | "html" です。

高度なランタイムオプション​

次のフィールドも CliConfig に含まれます。requester、maxEvents、maxStreamMs、maxResponseSize は JSON 設定ファイルで指定できます。signal、httpRuntime、resolveTransport は JSON 設定ではなく実行時のオブジェクトなので、設定の解決後にコードから runTests() へ直接渡してください。

interface AdvancedRuntimeOptions {
  requester?: {
    followRedirects?: boolean;
    maxRedirects?: number;
    disableCookies?: boolean;
    protocolVersion?: "http1" | "http2" | "auto";
  };
  maxEvents?: number;
  maxStreamMs?: number;
  maxResponseSize?: number;
  signal?: AbortSignal;
  httpRuntime?: { certificates?: unknown; fileResolver?: unknown };
  resolveTransport?: (target: { protocol: string; url?: string }) => Promise<
    Pick<CliConfig, "proxy" | "tls" | "httpRuntime">
  >;
}

requester は HTTP リダイレクト、Cookie、プロトコル選択を制御します。HTTP/SSE では maxEvents の既定値は 50 で、maxStreamMs は未指定なら timeout を使用します。maxResponseSize はリクエストランタイムに渡されます。gRPC のストリーム期限には maxStreamMs、次に timeout、最後に 30000 ミリ秒が使われます。signal は実行をキャンセルし、httpRuntime は HTTP の証明書・ファイル処理を提供し、resolveTransport は対象ごとのトランスポート設定を解決します。

DEFAULT_CONFIG​

ライブラリからエクスポートされる組み込みの既定値オブジェクトです。

export const DEFAULT_CONFIG: Required<
  Pick<
    CliConfig,
    "outputDir" | "formats" | "concurrency" | "timeout" | "failOnError" | "grpcReflection" | "mcpTransport"
  >
> = {
  outputDir: "./openapi-cli-report",
  formats: ["json", "cli", "html"],
  concurrency: 5,
  timeout: 30000,
  failOnError: true,
  grpcReflection: true,
  mcpTransport: "streamable-http",
};

FilterConfig​

フィールド型説明
methodsstring[]指定した HTTP メソッドのみテスト。例：["get","post"]。設定ファイルでは小文字を使用し、CLI 入力は自動的に正規化される
pathsstring[]いずれかの正規表現に一致するパスのみテスト。正規表現が無効なら部分文字列照合に切り替える
tagsstring[]いずれかの指定タグを持つ操作のみテスト
operationIdsstring[]指定した operationId と完全一致する操作のみテスト

キーがないフィルターは undefined に解決され、すべての操作が実行されます。

TlsConfig​

フィールド型説明
caCertstringCA 証明書バンドル（PEM）のパス
clientCertstringmTLS 用クライアント証明書（PEM）のパス
clientKeystringmTLS 用クライアント秘密鍵（PEM）のパス
strictSSLbooleanfalse で TLS 証明書検証を省略。安全ではない
pfxstringPFX 証明書バンドルのパス。gRPC では PEM が必要
passphrasestring暗号化された証明書素材のパスフレーズ

注：CLI オプション --insecure は tls.strictSSL = false に対応し、検証を無効化します。

AuthConfig​

フィールド型説明
typeAuthConfig["type"]認証方式。対応する名前は下記を参照
parametersRecord<string, string | number | boolean>リクエストランタイムへ渡す認証方式固有のパラメーター
tokenstringtype: "bearer" 用の Bearer トークン
usernamestringtype: "basic" 用のユーザー名
passwordstringtype: "basic" 用のパスワード
keystringtype: "apikey" 用の API キー名
valuestringtype: "apikey" 用の API キー値
in"header" | "query"API キーを配置する場所

対応する type は bearer、basic、apikey、none、digest、oauth1、oauth2、jwt、hawk、aws4、ntlm、asap、edgegrid です。利用可否と必須パラメーターはプロトコルとリクエストランタイムによって異なり、名前の指定だけでは認証設定は完了しません。

現在、CLI の --bearer は { type: "bearer", token } のみを生成します。より詳細な basic / apikey 設定は設定ファイルから指定します。

JSON 設定ファイル​

設定ファイルは Partial<CliConfig> に従う通常の JSON です。--config <path> / -c で指定します。CLI 引数は常にファイルの値より優先されます。

{
  "specPath": "./openapi.json",
  "serverUrl": "https://api.staging.example.com",
  "outputDir": "./reports",
  "formats": ["json", "html"],
  "concurrency": 10,
  "timeout": 15000,
  "failOnError": true,
  "proxy": "http://proxy.corp:8080",
  "tls": {
    "strictSSL": true,
    "caCert": "./ca-bundle.pem",
    "clientCert": "./client.crt",
    "clientKey": "./client.key"
  },
  "headers": {
    "X-API-Key": "${API_KEY}",
    "X-Environment": "staging"
  },
  "auth": {
    "type": "bearer",
    "token": "${BEARER_TOKEN}"
  },
  "variables": {
    "host": "api.staging.example.com"
  },
  "filter": {
    "methods": ["get", "post"],
    "tags": ["v2", "public"],
    "paths": ["^/api/v2"],
    "operationIds": ["getUser", "createUser"]
  },
  "grpcReflection": true,
  "grpcProtoPaths": ["./proto"],
  "mcpTransport": "streamable-http",
  "mcpCommand": "npx",
  "mcpArgs": ["-y", "@modelcontextprotocol/server-everything"],
  "mcpCwd": "./mcp-servers"
}

ファイルがない場合は Config file not found: <path>、JSON が無効な場合は Invalid config file (must be JSON) がスローされます。

環境変数の展開​

--env / envFile で .env を読み込むと、次の文字列フィールド内の ${VAR_NAME} 参照が展開されます。

  • serverUrl
  • proxy
  • headers の値
  • auth.token
  • variables の値

例：

openapi-cli --spec openapi.json \
  --server 'https://${API_HOST}/v1' \
  --header 'Authorization: Bearer ${BEARER_TOKEN}'

.env の動作：既存の process.env エントリーは上書きしません。値を囲む単一・二重引用符は除去し、空行と # コメント行は無視します。ファイルがない場合は通知せずにスキップします。

プログラムでの設定構築​

import { resolveConfig, DEFAULT_CONFIG } from "@powerduck/openapi-cli";

const config = resolveConfig({
  spec: "./openapi.json",
  server: "https://api.staging.example.com",
  concurrency: 10,
  method: "get",
});

仕様が指定されていない場合、resolveConfig は "No OpenAPI spec path provided..." をスローします。proxy が有効な URL でない場合は Invalid proxy URL: <url> をスローします。