OpenAPI定義から特定の要素だけ取り出すスクリプト
前置き 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...}" のような構文で、別の場所で定義されている要素を参照できる。 1 2 3 4 5 6 7 8 9 10 11 12 /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 が参照する先のリソースも漏らさずスキーマとして抽出する必要がある。 ...