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

Mac+Docker環境にて、Android向けのクライアントAPIを作成するまでの手順や流れをまとめてみる。

Android側の仕様はRxJava&Retrofit2を使っていくスタイル。
前提としてDockerおよびMavenの環境と、Java7 or Java8がインストールされていること

#Swagger-Editorでyamlを作る
一番簡単な方法は[ここ](http://editor.swagger.io/#/)で編集する。
ただ、社内のAPIを外部のサイトに書くのはちょっと…という場合はDockerが用意されているのでそれを使うと良い

## DockerでSwagger-Editorを動かす
Docker-Hubに上がっているので、それを持ってくるだけでよい。コマンドは以下のとおり([公式](https://github.com/swagger-api/swagger-editor)より)

```command
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を出力する
[公式](https://github.com/swagger-api/swagger-codegen)を見れば(英語だけども)すべてが書いてあるので、一読推奨。

## Swagger-Codegenをビルドする
今回はmvnを使う方法を記載。
(brewでインストールしてもいいが、このあとテンプレートをカスタマイズするのでgit cloneを使うものにしたかった)

```command
git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen
mvn clean package
```

## テンプレートを編集する
デフォルトのままではRetrofitやOkHttp、RxJavaなどのバージョンが古いケースがあるのでテンプレートを修正してしまう。
修正するファイルはRetrofit2の場合、swagger-codegenのルートから見て、以下の場所にある。
**修正後はswagger-codegenのパッケージを再ビルドするのを忘れずに**

```command
cd modules/swagger-codegen/src/main/resources/Java/libraries/retrofit2/
```

このフォルダ内にある、pom.mustacheやbuild.gradle.mustacheを書き換えれば良い。その他のライブラリのバージョンも古いので更新推奨。
(sbtでAPIをビルドする人はsbt.mustacheを修正)

```xml: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>
```

```groovy: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](https://github.com/swagger-api/swagger-codegen#customizing-the-generator)」の章に書いてある。
Retrofit2でAPIを吐き出す場合の例は以下のような感じ。

```json:config_sample.json
{
  "groupId":"com.my.company",
  "artifactId":"MyClient",
  "artifactVersion":"1.0.0",
  "library":"retrofit2"
}
```

## APIファイルを出力する
ここまで準備できてしまえば後はコマンドを２回叩くだけ

```command
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をビルドする。

```command:ローカル環境にmavenでインストール
cd output/directory
mvn clean install
```

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

Let's 自動化