OpenAPI定義から特定の要素だけ取り出すスクリプト

Sun, 26 Apr 2026 15:05:00 +0900

前置き

OpenAPIスキーマからAPIクライアントを作りたい。そういう場合 OpenAPITools/openapi-generator を使って生成することになるが、スキーマがあまりにもでかすぎると困る。

yamlだとファイルがでかすぎるとうまく読めない
Pythonのようなインタプリタ型のクライアントだとモジュールのロードに時間がかかる

一例として、以下のAPIスキーマを見てほしい。以下はネットワーク仮想化製品であるVMware NSX-TのAPIスキーマであるが、nsx_policy_api.yml を見ると、テキストファイルなのに12MGもある。jsonファイルですら8.6MBである。

NSX-T Data Center REST API

こういった外部製品のAPIクライアントを作ることを考えたとき、実際には特定のAPIしか叩かないだろう。もしその特定のAPIのスキーマと関連リソースだけを抽出したスキーマを作れば、軽量なAPIクライアントが作成できることが期待される。

というわけで本記事では、OpenAPIのスキーマから必要なリソースと関連リソースだけを抽出した新しいスキーマを生成するスクリプトを作成する。

設計

今回の目的は「特定のAPIと関連リソースのみを抽出する」ことである。

入出力

そのため、入力と出力はそれぞれ次のようになる。

入力：
- OpenAPI定義ファイル
- OpenAPI定義ファイルに含まれるAPIパスのリスト
出力： OpenAPIスキーマ
- 最もファイルサイズを占めているであろう以下の属性には必要最低限のものが入っている状態となっている
  - paths
  - definitions (v2.0のみ)
  - parameters (v2.0のみ)
  - responses (v2.0のみ)
  - components (v3.0のみ)
- OpenAPI には2.0と3.0があるが、特に取り決めない
  - OpenAPI Specification - Version 2.0 | Swagger
  - OpenAPI Specification - Version 3.0 | Swagger

インターフェース

APIパスのリストは、改行区切りで標準入力から受け取るものとする。

`1`	`python3 main.py -i input.yml -o output.yml`

API関連リソースを抽出するロジック

OpenAPIでは、$ref: "#/{attr...}" のような構文で、別の場所で定義されている要素を参照できる。

/pets:
  get:
    description: Returns all pets from the system that the user has access to
    produces:
    - application/json
    responses:
      '200':
        description: A list of pets.
        schema:
          type: array
          items:
            $ref: '#/definitions/pet'

このような $ref: ... があるため、完全なAPIスキーマとして抽出するためには、$ref が参照する先のリソースも漏らさずスキーマとして抽出する必要がある。

Swagger on Chanomic Blog

OpenAPI定義から特定の要素だけ取り出すスクリプト

前置き

設計

入出力

インターフェース

API関連リソースを抽出するロジック