Help us understand the problem. What is going on with this article?

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. サーバー側を担当しています。生成したクライアントの使い勝手はわかりません。 

ledsun
編集リクエスト、コメント大歓迎です。
luxiar
Ruby on Rails専門のWebアプリケーション開発に特化した町田の受託開発企業です
http://www.luxiar.com/index.html
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away