🌟

OpenAPI から 10分で Python クライアントを生成してみた

に公開
Python
OpenAPI
tech

概要

本記事では、データスペースと生成 AI・データ分析分野をつなぐPythonクライアントが、OpenAPIドキュメントからの自動生成で10分で完了した事例を紹介します。

想定読者

  • このライブラリ、Pythonで使えたらいいのに！と思ったことがある方

背景

データスペースに流通するデータの活用を考えたとき、単なるデータの共有や転送にとどまらず、アプリケーション側でデータを柔軟に活用・処理できる統合手段の整備が重要となります。Sovity 社は、データスペースにおけるデータの出入り口である「コネクタ」をアプリケーションのバックエンドとして使用するための API Wrapper を、 Java および TypeScript 向けに Community Edition として提供しています。一方で、生成 AI やデータ分析の分野においては Python が事実上の標準言語となっており、主要なライブラリやツール群も Python を前提に構築されています。そのため、これらの環境と EDC をシームレスに連携させるためには、Python 向けのクライアントの整備が必要であると考えました。これが、今回Pythonクライアントの自動生成の動機です。

実行環境

今回のクライアント自動生成は、以下の開発環境で実施しました：

  • OS：Windows 11 + WSL2（Ubuntu 22.04）
  • Python：3.10.13 (pyenvにてバージョン管理)
  • パッケージ管理・仮想環境：poetry（※必須ではありません）

Poetry を使用すると依存関係の管理やスクリプトの実行が簡潔になり、仮想環境の分離も自動で行われるため便利です。ただし、openapi-python-client 自体は pip でインストール可能な CLI ツールであるため、pyenvやPoetry を使わずともプロジェクト環境を構築することは十分に可能です。

実行手順

今回使用したOpenAPIドキュメントは、https://github.com/sovity/edc-ceにて公開されているeclipse-edc-management-api.yamlです。

まず、仮想環境でopenapi-python-clientをインストールします。

poetry init
poetry add --dev openapi-python-client
poetry install

次に、自動生成するライブラリ群のライブラリ名やパッケージ名などを定義する設定ファイル　openapi-config.json　を作成します。今回はパッケージ名、ライブラリ名ともにedc-management-clientとします。

{
  "class_overrides": {},
  "project_name_override": "edc_management_client",
  "package_name_override": "edc_management_client",
  "config": {
    "field_constraints": true,
    "use_enum_prefix": false
  }
}

その後、eclipse-edc-management-api.yamlと前の手順で作成した openapi-config.jsonを用いて自動生成を開始します。

poetry run openapi-python-client generate --path eclipse-edc-management-api.yaml --config openapi-config.json --meta poetry

すると、10秒足らずでライブラリ群が自動生成されます。なんとREADMEまで自動で。。。

これで、JavaとTypeScriptでしか提供されていなかったライブラリを、Pythonでも使えるようになったわけです！

細かな注意点

OpenAPI 3.0 に準拠していても openapi-python-client によって無効と判定され、自動生成がスキップされてしまう場合があります。

以下の例は、OpenAPI3.0に準拠したステータスコード "default"がopenapi-python-clientによって無効なステータスコードとして判定され、生成がスキップされた際のエラーコードです。

WARNING parsing POST /callback/{processId}/deprovision within http_provisioner_webhook.

Invalid response status code default (not a valid HTTP status code), response will be omitted from generated client

このような場合は、defaultに代えて明確なステータスコード(200,204など)に変更することでエラーを回避することが出来ます。

# before:
responses:
  default:
    description: default response

# after:
responses:
  '204':
    description: Successfully processed without content

ただ、"default" は「定義されていないあらゆるステータスコード」を受け入れることを意味するため、これを 200 や 204 に置き換えると、実際のレスポンスと OpenAPI の記述がずれ、実装と仕様との乖離が発生するリスクがあります。OpenAPIドキュメントに"default"ステータスが含まれる場合、本番環境での使用は非推奨です。

Discussion