要約

• swaggerの説明
• 使い方

背景

クライアントとサーバーの実装者が分かれていて情報共有に時間がかかる状況です。
事前にAPIの仕様だけは固めて共有しておきたいです。

ただ、手書きのドキュメントの場合は曖昧な表現が残り、誤解が生じる可能性があります。
ドキュメントのバリデーションができると嬉しいです。
欲を言えば、仕様の動作を確認するためのスタブサーバが作れると嬉しいです¹。

そこでswaggerを使います。

swaggerとは？

SwaggerはWeb APIのドキュメンテーション仕様と、それを作る・使うツール群です。

ドキュメンテーション仕様

最新のドキュメンテーション仕様はOpenAPI 3.0です。
ツール群の対応が終わっていません。
現時点では、前身のSwagger 2.0を使います。

Swagger Editor

Swagger Editor はSwagger 2.0を編集するための、エディタです。
WYSIWYGでAPI仕様が書けます。

オンラインエディタが提供されています。
どんなものかイメージを掴むのは、これを触ってみるのが良いでしょう。

オフラインで利用したい場合は、Dockerイメージも提供されています。

docker run --rm -d -p 80:8080 swaggerapi/swagger-editor

を実行すれば、 http://localhost で利用できます。

Swagger Codegen

Swagger Codegenは Swagger 2.0 から、各種言語のAPIクライアントまたはスタブサーバーを生成するツールです。

前述のSwagger Editorに組み込まれており、Create Serverタブ、Create Clientタブから生成できます。
生成されるコードが持つ機能は言語によってマチマチです。

例えば、現時点の最新バージョン 2.3.1 で生成した、Ruby on Rails 5のスタブサーバーは起動できません。
masterブランチでは修正されています（しました）。

masterブランチ

masterブランチを利用するには、Github上で公開されているソースコードを使います。
Swagger CodegenはJava7以上でないと動かないことに注意してください。

必要であれば、JAVA_HOMEを設定してください。

export JAVA_HOME=`/usr/libexec/java_home -v 1.8`
export PATH=${JAVA_HOME}/bin:$PATH

git clone 〜 依存パッケージの取得

git clone [email protected]:swagger-api/swagger-codegen.git
cd swagger-codegen
mvn clean package

ビルド

./mvnw clean package

実行

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i ~/swagger_test/swagger.yaml -l rails5 -o ~/swagger_test/rails5

Ruby on Rails 5のスタブサーバーを生成する例です。

カスタマイズ

各言語の生成機能はモジュール化されています。
ソースコードは swagger-codegen/modules/swagger-codegen/src/main/ 配下にあります。
この中には

• java
• resources

の２つのディレクトリがあります。

テンプレート

主に変更するのは、resourcesディレクトリに入っているテンプレートです。
例えば、Rails５のコントローラーのテンプレートはcontroller.mustache です。

ファイル名の通りmustache形式のテンプレートファイルです。

ソースコード

javaディレクトリにはCodegenConfigを実装したクラスが入っています。

例えば java/io/swagger/codegen/languages/Rails5ServerCodegen.javaです。

プラグインのインターフェース CodegenConfig

プラグインはCodegenConfig型で扱われます。

Codegen.java:L123

public static List<CodegenConfig> getExtensions() {
    ServiceLoader<CodegenConfig> loader = ServiceLoader.load(CodegenConfig.class);
    List<CodegenConfig> output = new ArrayList<CodegenConfig>();
    for (CodegenConfig aLoader : loader) {
        output.add(aLoader);
    }
    return output;
}

ServiceLoaderは、Javaでプラグインを作るために仕組みです。
この仕組みを使って、引数で指定された言語に合わせて、生成するコードを切り替えています。

参考：ServiceLoaderでプラグインの仕組みをさくっと作る。 - うなの日記

実装クラス

実装クラスは[言語名]ServerCodegenです。
直接的はDefaultCodegenを継承します。

Rails5ServerCodegen.java:L26

public class Rails5ServerCodegen extends DefaultCodegen implements CodegenConfig

つまり、Rails5ServerCodegenで上書きされていればカスタマイズされた動作、されていなければ
DefaultCodegenの動作をします。

Swagger2Markdown

Swagger2Markdownは Swagger 2.0 からMarkdown形式のAPI仕様書を生成します。

dockerイメージが提供されています。

docker run --rm -v (pwd):/opt swagger2markup/swagger2markup convert -i /opt/swagger.yaml -f /opt/swagger -c /opt/config.properties

参考

• swagger 初めて触ってみた - Qiita
• SwaggerでRESTful APIの管理を楽にする - Qiita
• Swagger Code Generator (swagger-codegen) の server stub の レスポンスが empty object になるのなんで？ - Qiita
• Swaggerを使ってAPIの繋ぎ込みを楽にするための取り組み | GRIPHONE ENGINEER'S BLOG