Edited at

Swaggerを使ってAPI仕様を共有する

More than 1 year has passed since last update.


要約


  • swaggerの説明

  • 使い方


背景

クライアントとサーバーの実装者が分かれていて情報共有に時間がかかる状況です。

事前にAPIの仕様だけは固めて共有しておきたいです。

ただ、手書きのドキュメントの場合は曖昧な表現が残り、誤解が生じる可能性があります。

ドキュメントのバリデーションができると嬉しいです。

欲を言えば、仕様の動作を確認するためのスタブサーバが作れると嬉しいです1

そこで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 git@github.com: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

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


テンプレート

主に変更するのは、resourcesディレクトリに入っているテンプレートです。

例えば、Rails5のコントローラーのテンプレートは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


参考





  1. サーバー側を担当しています。生成したクライアントの使い勝手はわかりません。