Edited at

Swagger Codegen のPHP実装があまりにアレだったので、ライブラリ自作して公開してみた

More than 1 year has passed since last update.

** 2017/4/27 Photocreateさんの名前で再公開させていただきました。 **


はじめに

Swaggerには、RESTful APIに関する仕様やツールセットがあり、ドキュメントとコードを一元管理する強力な仕組みがあります。

その他、Swaggerそのものについては、下記のリンクに詳しく書かれているので、参照してみてください。

最近、個人的に使っているAWSAPI Gatewayは、Swagger定義ファイルを使ったインポート、エクスポートに対応しています。


Swagger CodegenでAPIクライアント作成してみたところ

SwaggerでPHPのAPIクライアントを生成してみたのですが、うーんという感じです。

下記のリンクからコードを見てみてください。

https://github.com/swagger-api/swagger-codegen/tree/master/samples/client/petstore/php/SwaggerClient-php/lib

僕は下記のような印象を持ちました。


  • ぱっと見、コードベースが大きい


  • 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の定義を網羅するには、まだまだ実装が足りないので、実際の現場で活用しながらアップデートしていきたいと思います。

使ってみてフィードバックいただけましたら、幸いです。

ではでは。