manage-openapi-overlays

manage-openapi-overlays

オーバーレイを使うと、ソースを変更せずに SDK 生成用の OpenAPI 仕様をカスタマイズできます。このスキルでは、オーバーレイファイルの作成、仕様への適用、検証エラーの修正方法を説明します。

コンテンツガイド

トピック	ガイド
OpenAPI の検証	content/validation.md
セキュリティスキーム	content/security-schemes.md

これらのガイドでは、仕様の検証、よくある問題の修正、認証方式の設定について説明します。

認証

環境変数 SPEAKEASY_API_KEY を設定するか、speakeasy auth login を実行してください。

使用するタイミング

オーバーレイファイルを手動で操作する必要があるときに、このスキルを使用してください。

• 特定の JSONPath ターゲットを指定して、オーバーレイファイルを一から作成する
• 既存のオーバーレイファイルを仕様に適用する
• オーバーレイの構文と構造を検証する
• 2 つの仕様を比較してオーバーレイを生成する
• オーバーレイの仕組み（actions、targets、update/remove）を理解する
• オーバーレイを手動で作成して lint の問題を修正する
• ユーザーが「create overlay」「apply overlay」「overlay file」「manual overlay」「overlay syntax」「JSONPath targeting」「validate overlay」と言った場合

対象外：AI を活用した命名候補の提案（代わりに improve-sdk-naming を参照してください）

入力

入力	必須	説明
対象の仕様	はい	カスタマイズまたは修正する OpenAPI 仕様
カスタマイズ内容	条件による	適用する変更（グループ、名前、再試行、説明）
オーバーレイファイル	条件による	適用する既存のオーバーレイ（適用ワークフローの場合）
lint 出力	あると便利	修正する検証エラー（修正ワークフローの場合）

出力

出力	説明
オーバーレイファイル	JSONPath を対象にした変更を含む YAML ファイル
変更済みの仕様	変換された OpenAPI 仕様（適用時）

コマンド

仕様を比較してオーバーレイを生成する

speakeasy overlay compare -b <before-spec> -a <after-spec> -o <output-overlay>

仕様の変更版があり、その差分を再利用可能なオーバーレイとして記録したい場合に使用します。

仕様にオーバーレイを適用する

speakeasy overlay apply -s <spec-path> -o <overlay-path> --out <output-path>

オーバーレイを検証する

speakeasy overlay validate -o <overlay-path>

オーバーレイを手動で作成する

次の構造でオーバーレイファイルを作成します。

overlay: 1.0.0
info:
  title: My Overlay
  version: 1.0.0
actions:
  - target: "$.paths['/example'].get"
    update:
      x-speakeasy-group: example
      x-speakeasy-name-override: getExample

各 action には target（JSONPath 式）と、update（マージするオブジェクト）または remove（ターゲットを削除するためのブール値）があります。

例：SDK メソッドの命名とグループ化

overlay: 1.0.0
info:
  title: SDK Customizations
  version: 1.0.0
actions:
  - target: "$.paths['/users'].get"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: list
  - target: "$.paths['/users'].post"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: create
  - target: "$.paths['/users/{id}'].get"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: get
  - target: "$.paths['/users/{id}'].delete"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: delete
      deprecated: true

これにより、次の SDK メソッドが生成されます：sdk.users.list()、sdk.users.create()、sdk.users.get()、sdk.users.delete()。

例：オーバーレイを適用する

# Apply overlay and write merged spec
speakeasy overlay apply -s openapi.yaml -o sdk-overlay.yaml --out openapi-modified.yaml

# Compare two specs to generate an overlay
speakeasy overlay compare -b original.yaml -a modified.yaml -o changes-overlay.yaml

ワークフローで使用する（推奨）

オーバーレイを手動で適用する代わりに、.speakeasy/workflow.yaml に追加します。

sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./naming-overlay.yaml
      - location: ./grouping-overlay.yaml

オーバーレイは順番に適用されます。後のオーバーレイは前のオーバーレイを上書きできます。この方法により、speakeasy run の実行時にオーバーレイが常に適用されます。

よくある修正パターン

ソース仕様を編集できない場合は、オーバーレイを使って検証の問題を修正します。

問題	オーバーレイによる修正
操作名が適切でない	操作に x-speakeasy-name-override を追加する
説明がない	操作に summary または description を追加する
タグがない	操作に tags 配列を追加する
操作のグループ化が必要	操作に x-speakeasy-group を追加する
再試行の設定が必要	操作または全体に x-speakeasy-retries を追加する
エンドポイントを非推奨にする	操作に deprecated: true を追加する
SDK 固有のメタデータを追加する	任意の x-speakeasy-* 拡張を追加する

修正ワークフロー

# 1. Validate the spec to identify issues
speakeasy lint openapi --non-interactive -s openapi.yaml

# 2. Create an overlay file targeting each issue (see patterns above)

# 3. Add overlay to workflow.yaml under sources.overlays

# 4. Regenerate the SDK
speakeasy run --output console

Speakeasy 拡張機能リファレンス

拡張機能（x-speakeasy-*）を使用して SDK の生成をカスタマイズできます。オーバーレイを通じて適用します。

拡張機能	適用対象	目的
x-speakeasy-retries	オペレーションまたはルート	再試行動作を設定します
x-speakeasy-pagination	オペレーション	自動ページネーションを有効にします
x-speakeasy-name-override	オペレーション	SDK メソッド名を上書きします
x-speakeasy-group	オペレーション	メソッドを名前空間の下にグループ化します
x-speakeasy-unknown-values	enum を含むスキーマ	不明な enum 値を許可します
x-speakeasy-globals	ルート	SDK 全体で使用するパラメーターを定義します
x-speakeasy-custom-security-scheme	セキュリティスキーム	複数パートのカスタム認証

再試行

actions:
  - target: "$.paths['/resources'].get"  # Or "$" for global
    update:
      x-speakeasy-retries:
        strategy: backoff
        backoff:
          initialInterval: 500      # ms
          maxInterval: 60000        # ms
          maxElapsedTime: 3600000   # ms
          exponent: 1.5
        statusCodes: ["5XX", "429"]
        retryConnectionErrors: true

ページネーション

オフセット／リミット：

actions:
  - target: "$.paths['/users'].get"
    update:
      x-speakeasy-pagination:
        type: offsetLimit
        inputs:
          - name: offset
            in: parameters
            type: offset
          - name: limit
            in: parameters
            type: limit
        outputs:
          results: $.data
          numPages: $.meta.total_pages

カーソル：

actions:
  - target: "$.paths['/events'].get"
    update:
      x-speakeasy-pagination:
        type: cursor
        inputs:
          - name: cursor
            in: parameters
            type: cursor
        outputs:
          results: $.events
          nextCursor: $.next_cursor

オープン enum（耐障害性）

API が新しい enum 値を返した際に SDK が破損しないようにします。

actions:
  - target: "$.components.schemas.Status"
    update:
      x-speakeasy-unknown-values: allow

すべての enum に適用する場合（オーバーレイのルートに x-speakeasy-jsonpath: rfc9535 を追加します）：

actions:
  - target: $..[?length(@.enum) > 1]
    update:
      x-speakeasy-unknown-values: allow

グローバルヘッダー

SDK 全体で使用するヘッダーをコンストラクターのオプションとして追加します。

actions:
  - target: $
    update:
      x-speakeasy-globals:
        parameters:
          - $ref: "#/components/parameters/TenantId"
  - target: $.components
    update:
      parameters:
        TenantId:
          name: X-Tenant-Id
          in: header
          schema:
            type: string

結果：client = SDK(api_key="...", tenant_id="tenant-123")

カスタムセキュリティスキーム

複雑な認証（HMAC、複数パートの認証情報）の場合：

actions:
  - target: $.components
    update:
      securitySchemes:
        hmacAuth:
          type: http
          scheme: custom
          x-speakeasy-custom-security-scheme:
            schema:
              type: object
              properties:
                keyId:
                  type: string
                keySecret:
                  type: string
  - target: $
    update:
      security:
        - hmacAuth: []

gen.yaml で envVarPrefix: MYAPI を設定すると、MYAPI_KEY_ID と MYAPI_KEY_SECRET の環境変数をサポートするコードが生成されます。

JSONPath ターゲティングリファレンス

ターゲット	選択対象
$.paths['/users'].get	GET /users オペレーション
$.paths['/users/{id}'].*	/users/{id} のすべてのオペレーション
$.paths['/users'].get.parameters[0]	GET /users の最初のパラメーター
$.components.schemas.User	User スキーマ定義
$.components.schemas.User.properties.name	User スキーマの Name プロパティ
$.info	API 情報オブジェクト
$.info.title	API タイトル
$.servers[0]	最初のサーバーエントリー

避けるべきこと

• オーバーレイを使用して、無効な YAML／JSON 構文エラーを修正しないでください。ソースファイルを修正してください
• 壊れた $ref パスをオーバーレイで修正しようとしないでください。ソース仕様を修正してください
• 誤ったデータ型を修正するためにオーバーレイを使用しないでください。これは API 設計上の問題です
• オーバーレイでスキーマを重複排除しようとしないでください。構造分析が必要です
• ソース仕様の修正が必要なエラーを無視しないでください。オーバーレイですべてを解決できるわけではありません
• 外部で管理されているソース OpenAPI 仕様を直接変更しないでください
• speakeasy overlay create コマンドを使用しないでください。そのようなコマンドは存在しません

トラブルシューティング

エラー	原因	解決策
"target not found"	JSONPath が仕様の構造と一致しません	仕様を確認して、パスと大文字・小文字が正確に一致しているか確かめてください
変更が適用されない	ワークフローにオーバーレイがありません	workflow.yaml の sources.overlays にオーバーレイを追加してください
"invalid overlay"	YAML の形式が正しくありません	オーバーレイの構造を確認してください。overlay、info、actions が必要です
YAML parse error	オーバーレイの構文が無効です	YAML のインデントと引用符を確認してください
変更が反映されない	ターゲットパスが間違っています	大文字・小文字も含めて正確なパスを指定した $.paths['/exact-path'] を使用してください
オーバーレイ適用後もエラーが続く	オーバーレイでは解決できない問題です	ソース仕様の修正が必要な問題かどうか確認してください
オーバーレイの順序が競合している	後のオーバーレイが前のオーバーレイを上書きしています	workflow.yaml でオーバーレイの順序を変更するか、1 つのファイルにまとめてください

変更後の手順

オーバーレイファイルを作成または変更し、workflow.yaml に追加した後、SDK を再生成するようユーザーにプロンプトを表示してください。

オーバーレイの設定が完了しました。 speakeasy run で SDK を再生成しますか？

ユーザーが確認した場合は、次を実行します。

speakeasy run --output console

SDK にオーバーレイの変更を反映するには、再生成が必要です。