swagger specからSDKを作成できるswagger-codegenを試してみた

はじめに

WebAPIの仕様書として確固たる地位を確立したswagger、現在はOpenAPI Specificationとして知られています。今回はswagger-codegenというOSSを使って、Apitoreのswagger specからSDKを自動生成してみました。

余談

PythonのKubernetes SDKを使っていたらバグらしきものを見つけたのでissuePRを上げたところ

「それ、swagger-codegen使って自動生成してるんだよね。そして既知のissue」

ということで、swagger-codegenを知りました。Kong以外のSDK自動生成ツールは知らなかったのでラッキーでした。

なお、swagger-codegenのバグ?については既にたくさんのPRが溜まってたので「きっともうPR上がってるか近いうちに誰か解決するだろう」と放置を決め込みました(すいません)。

生成したSDK

Apitore Python SDK

swagger-codegenでSDKを生成する方法

公式に則ってやれば間違いありません。私は(元?)Java maven使いなので、mavenでライブラリをビルドしました。ビルド済みのライブラリもダウンロードできるみたいです。

$ git clone https://github.com/swagger-api/swagger-codegen.git
$ cd swagger-codegen
$ mvn clean package

生成できるSDKの言語はたくさんあるみたいです。Java、Python、Ruby、NodeJSなどなど。今回はPythonのSDKを生成してみます。必要な情報はswagger specのみです。幸いなことに、Apitoreではswagger UIもswagger specも公開しています。例えば形態素解析(Kuromoji+Neologd)のWebAPIはswagger UIがこちらでswagger specはこちらです。さっそくPythonのSDKを生成してみましょう。

$ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i https://api.apitore.com/json/7 -l python -o ./tmp/python/7

簡単にSDKが生成できました。生成したPython SDKはこちらで公開しています。

swagger-codegenで作ったSDKを利用してみる

試しに使ってみます。 apis 直下にアクセス用のクラスがあります。

$ cd ./tmp/python/7
$ pip install -r requirements.txt
$ python
>>> from swagger_client.api.kuromoji_ipadic_controller_api import KuromojiIpadicControllerApi
>>> api = KuromojiIpadicControllerApi()
>>> response = api.tokenize_using_get(access_token="your access_token", text="こんにちは世界")

使えました。これは便利ですね。

おわりに

swagger-codegenを試してみました。swagger specさえあれば色んな言語のSDKが自動生成できるのは大変にありがたいですね。個人的にswaggerを使うと開発が楽になるので、Apitoreではswagger specを自動生成するようにしています。一気に各言語のSDKが作れるとなると、WebAPIの布教活動が加速しますね!

なお、残念ながらswagger-codegenによるPythonのSDK生成では「listを必須項目とみなしてしまう」バグがあって、例えばKubernetesの場合だとcreate_namespaced_horizontal_pod_autoscalerread_namespaced_horizontal_pod_autoscalerが絶対にExceptionが起きます。開発は日々進んでいるので、早めにバグが直るといいな(PR出すか?)

2コメント

  1. とても参考になりました。ありがとうございます。
    以前使った時は、使い物にならないなーという感じでしたが、また使ってみようと思います。

    1. komikoniさん
      SDKを自動で作ってくれるので便利でした。swagger-codegenの非公式派生がopenapi-codegenっていうのが個人的にツボでした。

      PS
      API meetup最近行けてなくて申し訳ないです!

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です