swagger-codegenですわっとscaffoldingせん

こんにちは. 今回は(swagger-codegen)https://github.com/swagger-api/swagger-codegenを使ったりカスタマイズしてみようの会です.

swagger-codegenとは?

リポジトリのへのリンク github - swagger-codegen

Overview This is the swagger codegen project, which allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Spec. Currently, the following languages/frameworks are supported:

swagger-codegenは,swaggerエコシステムのツールの一つであり, OpenAPI3.0仕様(もしくはSwagger2.0仕様)から, クライアントライブラリやサーバのスタブ, ドキュメントを生成するツールです.

swagger自体とその周辺ツールについては, おおむね知っている前提で話を進めていきます.

swagger-codegenを使う動機

今回はサーバ側コードのscaffoldingを行うことを目的にswagger-codgenを使用します.

リポジトリのreadmeにあるように,基本的にはswagger-codegenで生成したものは プロダクション環境ではドキュメントとクライアントライブラリのみを使用することを想定されています(サーバはスタブのみ)

しかしながら,スタブ生成の出力先言語/フレームワーク一覧を見てみると, 以下のようになっています.

Server stubs: Ada, C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST), Kotlin, PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (rust-server), Scala (Finch, Lagom, Scalatra)

注目したのは

  • MSF4J
  • JAX-RS: CDI, CXF, Inflector, RestEasy

のように,scafoldingに対応していないフレームワークのコード生成も行ってくれることです. そこで,今回はswagger-codegenでサーバスタブを生成し, そのコードを足場(scafold!)として開発を行っていきます.

やってみよう!

コード生成自体は,Open API仕様のjsonyamlを用意すれば簡単に行えます. 今回はswaggerプロジェクト公式で配布しているサンプルを使用します.

1. OpenAPI仕様のファイルの準備

サンプルへのリンク このリンクから今回使用するサンプルファイルを取得します. 自分で用意する場合は,swagger-editor等のツールを使用して用意するのがいいと思います. ~(ただ正直swagger-editorを使ってもかなり定義する部分があるので結構大変です)~

2. コード生成

コード生成はおおむね2つの方法があります.

  1. swagger-editorで生成
  2. ローカルでビルド or jarを取得して生成

swagger-editorで生成

先ほど紹介したswagger-editorにコード生成機能が実装されています.editorにjson or yamlをはりつけて上部リンクの Generate ServerGenerate Clientから生成対象の言語/フレームワークを選択すれば,生成されたコードがzip圧縮したものが入手できます.

ローカルで生成

swagger-codegenのreadme内getting Startedにあるように,ソースコードを取得してからビルドすることで,実行可能jarを入手できます.ただ,ビルド済みのjarがmavenリポジトリ 上に配置されているため,ここからjarを取得する方が早いです.

コード生成コマンド

jarを取得した後は,以下のコマンドでコード生成ができます.

java -jar swagger-codegen-cli.jar generate -i [swagger.yaml or json]\
   -l [生成対象の言語/フレームワーク] \
   (-o [生成先フォルダ]\)
   (-c [config.jsonへのパス]\)
生成可能言語/フレームワーク一覧表示

生成可能な対象は以下のコマンドでリストを見ることができます

java -jar swagger-codegen-cli.jar langs 
生成対象言語/フレームワーク毎の設定項目表示

生成対象によってはconfig.jsonでオプションを設定できます. 例えばjava-play-framework向けの設定項目を調べるには以下のコマンドを使います.

 java -jar .\hoge.jar  config-help -l java-play-framework
生成結果

実際にコードを生成すると,フレームワークに応じたファイルが出力されます. これら生成されるコードを利用することでmodelやapiのための記述量を減らすことができます.

 java -jar .\hoge.jar  generate  -l java-play-framework -i http://petstore.swagger.io/v2/swagger
.json -o out
[main] INFO io.swagger.parser.Swagger20Parser - reading from http://petstore.swagger.io/v2/swagger.json
...

└─out
    ├─.swagger-codegen
    ├─app
    │  ├─apimodels
    │  ├─controllers
    │  └─swagger
    ├─conf
    ├─project
    └─public

生成されるコードについては生成対象ごとのテンプレート次第です. なので気に食わなかった場合はテンプレートのカスタマイズ,ロジックのカスタマイズを行っていきましょう.

後半(カスタマイズ編)に続く(予定)

参考リンク