swaggerでAndroid向けAPIを作成するまでの流れ

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を修正)

pom.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>

build.gradle.mustache

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を吐き出す場合の例は以下のような感じ。

config_sample.json

{
  "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をビルドする。

ローカル環境にmavenでインストール

cd output/directory
mvn clean install

最後に

APIのジェネレート自体はswagger-codegen-cli.jarさえあれば他の言語もできるので、社内のサーバに公開して、Githubへのコミットをフックして自動ビルドして公開、なんてのも簡単にできる。

Let's 自動化