Mac+Docker環境にて、Android向けのクライアントAPIを作成するまでの手順や流れをまとめてみる。
Android側の仕様はRxJava&Retrofit2を使っていくスタイル。
前提としてDockerおよびMavenの環境と、Java7 or Java8がインストールされていること
#Swagger-Editorでyamlを作る
一番簡単な方法はここで編集する。
ただ、社内のAPIを外部のサイトに書くのはちょっと…という場合はDockerが用意されているのでそれを使うと良い
DockerでSwagger-Editorを動かす
Docker-Hubに上がっているので、それを持ってくるだけでよい。コマンドは以下のとおり(公式より)
docker pull swaggerapi/swagger-editor
docker run -p 80:8080 swaggerapi/swagger-editor
あとは立ち上がったページ(http://(DockerのIP)/#/)にアクセスすればSwagger-Editorが開かれる
yamlファイルをダウンロードする
swagger-EditorのFile>「Download YAML」をクリックすればDLできる
Swagger-CodegenでAPIを出力する
公式を見れば(英語だけども)すべてが書いてあるので、一読推奨。
Swagger-Codegenをビルドする
今回はmvnを使う方法を記載。
(brewでインストールしてもいいが、このあとテンプレートをカスタマイズするのでgit cloneを使うものにしたかった)
git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen
mvn clean package
テンプレートを編集する
デフォルトのままではRetrofitやOkHttp、RxJavaなどのバージョンが古いケースがあるのでテンプレートを修正してしまう。
修正するファイルはRetrofit2の場合、swagger-codegenのルートから見て、以下の場所にある。
修正後はswagger-codegenのパッケージを再ビルドするのを忘れずに
cd modules/swagger-codegen/src/main/resources/Java/libraries/retrofit2/
このフォルダ内にある、pom.mustacheやbuild.gradle.mustacheを書き換えれば良い。その他のライブラリのバージョンも古いので更新推奨。
(sbtでAPIをビルドする人はsbt.mustacheを修正)
<!-- これより上は省略 -->
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<java.version>{{#java8}}1.8{{/java8}}{{^java8}}1.7{{/java8}}</java.version>
<maven.compiler.source>${java.version}</maven.compiler.source>
<maven.compiler.target>${java.version}</maven.compiler.target>
<swagger-core-version>1.5.9</swagger-core-version>
<retrofit-version>2.1.0</retrofit-version> <!-- ここ -->
{{#useRxJava}}
<rxjava-version>1.1.6</rxjava-version> <!-- ここ -->
{{/useRxJava}}
{{^java8}}
<jodatime-version>2.9.4</jodatime-version>
{{/java8}}
<oltu-version>1.0.1</oltu-version>
<junit-version>4.12</junit-version>
</properties>
ext {
oltu_version = "1.0.1"
retrofit_version = "2.0.2" //ここ
swagger_annotations_version = "1.5.8"
junit_version = "4.12"
{{#useRxJava}}
rx_java_version = "1.1.3" //ここ
{{/useRxJava}}
{{^java8}}
jodatime_version = "2.9.3"
{{/java8}}
}
コンフィグファイルを用意する
コンフィグファイルを用意することで、ArtifactIdやバージョンの管理などを外出しできる。
一応ビルド時のコマンドでも指定できるが、管理が圧倒的に面倒。
なお、Configファイルの記載はJSON形式。
詳しくは公式の「customizing-the-generator」の章に書いてある。
Retrofit2でAPIを吐き出す場合の例は以下のような感じ。
{
"groupId":"com.my.company",
"artifactId":"MyClient",
"artifactVersion":"1.0.0",
"library":"retrofit2"
}
APIファイルを出力する
ここまで準備できてしまえば後はコマンドを２回叩くだけ
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
-i input/your_api.yaml \
-l java \
-o output/directory \
-c path/to/config_sample.json
-iでインプットファイルの場所、-lで出力する言語(今回はJava)、-oで出力先、-cでコンフィグファイルの場所を指定する。
出力フォルダにはAPI生成用のソースコード一式が出力される(jarファイルそのものではないので注意)。
中にはAPIのソースコードと共にpom.xmlやbuild.gradleやbuild.sbtが一緒に出力されているので、環境に合わせてAPIをビルドする。
cd output/directory
mvn clean install
最後に
APIのジェネレート自体はswagger-codegen-cli.jarさえあれば他の言語もできるので、社内のサーバに公開して、Githubへのコミットをフックして自動ビルドして公開、なんてのも簡単にできる。
Let's 自動化