2018年6月13日水曜日

swagger-codegen を試してみた

概要

swagger-codegen は 1 つの swagger ファイルから複数の言語のクライアントツールを生成することができるツールです
コマンドラインと と docker で使えるので試してみました
今回は Ruby のコードを生成します

環境

  • macOS 10.13.5
  • docker 18.03.1-ce

docker で生成する

docker run --rm -v $(pwd):/local swaggerapi/swagger-codegen-cli generate -i http://petstore.swagger.io/v2/swagger.json -l ruby -o /local/out/ruby
  • ls -1 out/ruby/
Gemfile
README.md
Rakefile
docs
git_push.sh
lib
spec
swagger_client.gemspec

こんな感じで生成されました

homebrew でバイナリをインストールして生成

Mac であれば homebrew で swagger-codegen コマンドをインストールして使うことができます
ただし Java のインストールも必要です

  • brew cask install java
  • brew install swagger-codegen

Java8 が必要だと言われて怒られた場合は

  • brew cask install homebrew/cask-versions/java8

を実行してください

これで swagger-codegen というコマンドがローカルで使えるようになります
先程の docker も内部で同じコマンドを実行しています

生成するコマンドを実行してみます

swagger-codegen generate -i http://petstore.swagger.io/v2/swagger.json -l ruby -o ./out/ruby

ほぼ同じです
パスの部分が若干違うだけです
生成されるファイルは全く同じなので割愛します

と思ったのですが docker と homebrew だと swagger-codegen のバージョンが異なるようです
また生成されるファイルも若干違っていました
docker 版には .rubocup.yml がありましたが、homebrew 側にはありませんでした
docker 側は 2.4.0-SNAPSHOT で homebrew が 2.3.1 なので docker 側の最新イメージには開発中の最新版が入っているようです

サーバ側のコードを生成する

上記のコマンドはクライアント側のツールを生成するだけです
とりあえずリクエストを投げてみたいのでサーバ側のコードも生成してみましょう
Ruby の場合 Rails5 or Sinatra が選択できるようです
個人的に Sinatra のほうが好きなので Sinatra を選択します

docker run --rm -v $(pwd):/local swaggerapi/swagger-codegen-cli generate -i http://petstore.swagger.io/v2/swagger.json -l sinatra -o /local/out/ruby_server

当然ですが swagger.json は同じものを指定してください
docker を使っていますが、ローカルでコールする場合もほぼ同じです

生成されるファイルは以下の通りです

  • ls -1
Gemfile
README.md
api
config.ru
lib
my_app.rb
swagger.yaml

使ってみる

このままでは絵に書いた餅です
実際に使ってみます
今回は docker で生成したコードを使います

サーバを立てる

先ほど生成したサーバ用のコードを使います
とりあえず Gemfile があるのでなすがままに bundle install してみましょう

  • bundle install --path vendor

いろいろとインストールされます
config.ru があるので、それを使って起動してみます

  • bundle exec rackup config.ru

これで localhost:9292 で起動します
もしバインドする IP を指定したい場合は -o 0.0.0.0 という感じで指定できます

クライアントからコールしてみる

サーバが起動したのでクライアントツールを使ってコールしてみます
こちらも Gemfile があるのでとりあえず bundle install しましょう

  • bundle install --path vendor

こちらもいろいろインストールされます
作成されたファイルを見ると swagger_client.gemspecRakefile があるのでどうやら専用の gem が作成できそうです

とりあえずそのまま作成してみましょう (ただ bundler/gem_tasks を使っていないので rake build することはできません)

  • bundle exec gem build swagger_client.gemspec

これで swagger_client-1.0.0.gem という gem ができあがります
あとはインストールして使いましょう

  • gem install swagger_client-1.0.0.gem

ethontyphoeus に依存していました
HTTP クライアントとして使っているので内部では libcurl を使っているっぽいです

サンプルコード

ではサーバ側のコードをコールしてみましょう
コール先は localhost:9292 なので SwaggerClient.configure で変更します
と言ってもサーバ側で何も実装していないので何も返ってきません

  • vim sample.rb
require 'swagger_client'

SwaggerClient.configure do |config|
  config.host = 'localhost:9292'
end

api_instance = SwaggerClient::PetApi.new
status = ['sample_status']

begin
  p api_instance.find_pets_by_status status
rescue SwaggerClient::ApiError => e
  puts "Exception when calling PetApi->add_pet: #{e}"
end

こんな感じでクライアントからコールすることができます
クライアント側のコードに README.md が出来ておりリファレンスも生成されているのでそれを参考にすると良いと思います

ちなみに localhost:9292/swagger.yml で定義ファイルを確認できます

最後に

swagger-codegen を使って Ruby のコードを生成し試してみました
正直まだまだ絶賛開発中な感じはします

また生成したコード (特にサーバ側) は本当に簡単なものだけなので、実際にサービス化するときはコーディングが必要になります

なので、生成されるコードをしっかりと読み解く時間も必要になるのは注意が必要です

参考サイト

0 件のコメント:

コメントを投稿