OpenAPI GeneratorでOpenAPI仕様からPython製APIクライアントの生成をお試し〜SlackのpostMessageエンドポイントを例に〜

はじめに

2023年、大変お世話になりましたぴょん！ nikkieだぴょん！
よいお年をお迎えくださいぴょんぴょん〜¹

先日OpenAPI仕様を書いて、GPTからSlackに投稿しました。
その中でOpenAPI仕様にすごく可能性を感じたので、ちょっと興味の向くままに素振りしてみました。

なお、OpenAPIは絶賛キャッチアップ中なので、正確ではない点があるかもしれません。
用語の使い方はあんまり自信がなく、お気づきの点がありましたらご指摘いただけるととても嬉しいです（Twitter @ftnext）。

OpenAPI仕様に感じた可能性

GPTからSlack投稿の記事はこちらです。

Slack Appの作成（Web UI操作）とOpenAPI仕様（YAMLファイル）の記載をしただけで、GPTからSlackに投稿できました。

これってすごくないですか？
駆け出しの頃の私はSlackのAPIを叩くにもうまくいかないことが多く、何回かの試行錯誤の末にようやく成功と歩んでいました。
対して、GPTは一発です。

それを可能にしていると思うのが、OpenAPI仕様。
OpenAPI仕様として表現したら、APIの呼び出し方は一意に決まるってところがすごいですね。
過去に通ってきた（Slackに限らない）API呼び出しの試行錯誤、これからは全部回避できるのでは、と可能性を感じます。

もう少し調べていくと、OpenAPI仕様からクライアントライブラリを生成できるプロジェクトがあることを知ります。
その名は「OpenAPI Generator」

これは（タレコミのとおりだとしたら）やばいですよ！
これまでの開発経験の中でAPIクライアントを書くことはそれなりにあったわけですが、その作業から全部解放される！

DockerイメージでOpenAPI Generatorを動かす

今回はDockerイメージで動かす方法を選択しました。
https://github.com/OpenAPITools/openapi-generator/tree/v7.2.0#16---docker

https://hub.docker.com/r/openapitools/openapi-generator-cli

docker run --rm \
  -u $(id -u):$(id -g) \
  -v $PWD:/local \
  openapitools/openapi-generator-cli:v7.2.0 generate \
  --input-spec /local/slack-post-api.yml \
  --generator-name python \
  --output /local/out

カレントディレクトリにoutディレクトリを作り、その中にPython製クライアントライブラリを配置します。
オプションの説明はdocker run --rm openapitools/openapi-generator-cli:v7.2.0 help generateで見られます

--input-spec（-i）
- YAMLファイルのパスの他、URLもOK
--generator-name（-g）
- 一覧 https://openapi-generator.tech/docs/generators
--output（-o）

python generatorはこちら

Pydanticを使ったクライアントライブラリが生えました²。

out
├── README.md
├── docs
├── git_push.sh
├── openapi_client
├── pyproject.toml
├── requirements.txt
├── setup.cfg
├── setup.py
├── test
├── test-requirements.txt
└── tox.ini

pyproject.tomlがあることでPythonプロジェクトになっています。
生成されたコード一式をGitHubで公開して配布することもできますね

SlackのpostMessageエンドポイントのPythonクライアントを生成

GPTs記事で書いたOpenAPI仕様にBearerトークンによる認証を追加します。

/chat.postMessagepathのpostにsecurityを追加
componentsを追加

python generatorのドキュメントを見たところ、generateSourceCodeOnlyという設定値がありました。
今回の素振りにはクライアントライブラリのコードだけで十分なので、この設定値をtrueに設定します。
設定はJSONに書いて、generateコマンドにJSONファイルのパスを渡すようです

{
    "generateSourceCodeOnly": true
}

docker run --rm \
  -u $(id -u):$(id -g) \
  -v $PWD:/local \
  openapitools/openapi-generator-cli:v7.2.0 generate \
  --input-spec --input-spec https://gist.githubusercontent.com/ftnext/5fd660c35bf840bf6946324ffafa062d/raw/24877e72f5c8091548a2ff9033181d3bda43b2d6/slack-post-message-spec.yml \
  --generator-name python \
  --output /local/out \
  --config /local/config.json

生成されました。

out
├── openapi_client
└── openapi_client_README.md

outディレクトリ以下で仮想環境を作ります。
Python 3.11.4で動かしました。

% cd out
% python3.11 -m venv venv --upgrade-deps
% source venv/bin/activate

generateSourceCodeOnlyがfalse（デフォルト値）で実行して判明している依存ライブラリをインストール

% pip install 'urllib3<2.1.0' pydantic python_dateutil

ライブラリのバージョン

Package           Version
----------------- -------
annotated-types   0.6.0
pip               23.3.2
pydantic          2.5.3
pydantic_core     2.14.6
python-dateutil   2.8.2
setuptools        69.0.3
six               1.16.0
typing_extensions 4.9.0
urllib3           2.0.7

BEARER_TOKEN変数にSlack Appの「Bot User OAuth Token」を指定してpython インタプリタを起動。
コードはopenapi_client_README.mdの「Getting Started」から（一部手直ししています）

>>> import os
>>> import openapi_client
>>> configuration = openapi_client.Configuration(host="https://slack.com/api", access_token=os.environ["BEARER_TOKEN"])
>>> request = openapi_client.SendMessageRequest(channel="experiments", text="OpenAPI Generator製Pythonクライアントからの投稿")
>>> with openapi_client.ApiClient(configuration) as api_client:
...   api_instance = openapi_client.MessagesApi(api_client)
...   api_response = api_instance.send_message(request)
...

これでSlackに投稿できました🙌

OpenAPI仕様を書いたら、それを元にクライアントライブラリが生えました。
それを使ってAPI呼び出しできちゃったんです！

終わりに

OpenAPI Generatorの素振りの一歩目でした。
私はSlackを例にOpenAPI仕様を書いただけ。
それを元に前回はGPTにAPI呼び出しさせられましたし、今回はクライアントライブラリが生えました！

OpenAPI Generator、めっちゃ便利そう！ OpenAPIにキャッチアップしたい！
APIクライアントを作るというこれまで繰り返しやってきた開発が圧倒的に楽になるんじゃないかと期待しています。

先日OpenAPI Specを書いてGPTsからSlack投稿させたわけですが、
OpenAPI Specからクライアントライブラリを生成できるOpenAPI Generatorなるものを知り、https://t.co/8nHXh6Aixx
Specからわずか1コマンドでPython製Slack投稿クライアントができちゃいました！
これも1つのローコード。好感触
— nikkie / にっきー (@ftnext) 2023年12月31日

参考記事

P.S. 積ん読リスト

Software Design 2022年8月号に特集があるみたいです。

（2018年のWEB+DB PRESS Vol.108も見つかりました）

リポジトリには参考資料がまとまっています。
https://github.com/OpenAPITools/openapi-generator/tree/v7.2.0#5---presentationsvideostutorialsbooks

日本語記事も多くあり、今回の参考記事も見つけました

こちらとか気になりますね。

年始と対にしたんだぴょん！🐰✌️ ↩
「python-pydantic-v1」というgeneratorもあるようなのですがまだ触っていなくて、python generatorとの違いは分かっていません↩

nikkie-ftnextの日記

イベントレポートや読書メモを発信