Android
RxJava
Retrofit
swagger

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

More than 1 year has passed since last update.

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ファイルを出力する

ここまで準備できてしまえば後はコマンドを2回叩くだけ

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 自動化