** 2017/4/27 Photocreateさんの名前で再公開させていただきました。 **
はじめに
Swaggerには、RESTful APIに関する仕様やツールセットがあり、ドキュメントとコードを一元管理する強力な仕組みがあります。
その他、Swaggerそのものについては、下記のリンクに詳しく書かれているので、参照してみてください。
最近、個人的に使っているAWSのAPI Gatewayは、Swagger定義ファイルを使ったインポート、エクスポートに対応しています。
- Amazon API Gateway Swagger ImporterでAPIを一発で定義する ｜ Developers.IO
- Swagger 定義ファイルを使用して API Gateway API をインポートおよびエクスポートする - Amazon API Gateway
Swagger CodegenでAPIクライアント作成してみたところ
SwaggerでPHPのAPIクライアントを生成してみたのですが、うーんという感じです。
下記のリンクからコードを見てみてください。
僕は下記のような印象を持ちました。
- ぱっと見、コードベースが大きい
- ApiClientクラスは実質、HTTPクライアントだが、cURLで独自に実装するのではなく、Guzzleなど実績のあるライブラリに依存したほうがいい
- Generatorをカスタマイズすることもできるようだが、難しい上に満足できなさそうな気がする
とにかく自作してみる
最初にいくつかの短いスクリプトを書いて実行しました。
ポイントは下記のとおり。
- Swagger定義ファイルを入力として受け取る
- Swagger定義ファイルをパースして、ViewModel的なオブジェクトにまとめる
- Twigのテンプレートに、オブジェクトを渡して、renderする
- renderしたソースコードをファイルに出力する
- HTTPクライアントには、
Guzzleを使用
TwigをPHPのコード生成に使うのは、いささかトリッキーかと思ったのですが、Googleのapis-client-generatorなんかも、pythonのDjango Templateを使って、様々な言語のソースコードを生成しているので、メタプログラミング的な用途でも使っていけそうです。
どうせなら公開できるものにしよう
どうせなら、汎用的に使えるようなツールにしようということで、最初に書いたスクリプトをリファクタリングしてみました。
リファクタリングのポイントは下記のとおり。
- DIコンテナに、Pimpleを採用
- コマンドは、SymfonyのConsoleコンポーネントを使用
- 将来的にphp以外の言語も対応できるようにした（現在はphpのみサポートだが）
- Swaggerのサンプルプロジェクト（swaggerapi/petstore）をDocker Hubからインストールして、動作確認用に利用
ソースコードはパブリックなリポジトリにて公開していますので、ご確認ください。
https://github.com/Photocreate/api-client-generator
公開しました
packagistにも公開してありますので、composer requireしてみてください。
おわりに
Swaggerの定義を網羅するには、まだまだ実装が足りないので、実際の現場で活用しながらアップデートしていきたいと思います。
使ってみてフィードバックいただけましたら、幸いです。
ではでは。