Scalatra2.2+scalatra-swaggerでREST APIのリファレンスを生成する #1

#Scala

#REST

かけがわ

2013.02.10

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

Scalatra2.2リリース

つい先日、Scalatra2.2のstable版がリリースされました。今回のバージョンアップではかなり大きな機能追加や変更がされたようで、私はまだまだ内容が把握しきれていません。こちらで変更点が確認できますので是非チェックしてみて下さい。

Swagger

さて、本題です。SwaggerはREST APIのリファレンスを自動生成するためのフレームワークです。REST APIを提供するアプリケーションにおいて、Swaggerを利用してAPIの実装に必要な情報を追加すると、ブラウザで閲覧・実行が可能なリファレンスを生成することができます。

公式サンプル

こちらにSwaggerで生成されたリファレンスのデモサイトが公開されています。下のスクリーンショットのような、とても見やすいリファレンスが生成されます。

各リソースをクリックすると、さらにビューが展開して以下のような詳しい情報を見ることができます。

GET POST PUT DELETE

実行可能なリファレンス

また、生成されるリファレンスには、実際にエンドポイントのサーバーのAPIを叩いて結果を表示する機能も備わっています。試しに、リソースの詳細ビュー下部にある「Try it out!」ボタンを押下して、APIにリクエストを送ってみます。

すると、さらにビューが展開してレスポンスの情報が表示されます。

Swaggerの概要

Swaggerは、REST APIのリソースに関する情報を提供するサーバー側と、その情報を解析してリファレンスを表示するクライアント側から構成されています。クライアントは、サーバーからSwagger specというJSONもしくはXML形式のデータでリソースに関する情報を取得し、リファレンスのUIを生成します。

swagger-coreはREST APIの実装からSwagger specを生成するためのライブラリで、Scala/Javaで実装されています。REST APIを提供するアプリケーションは、このライブラリを利用してSwagger specを生成し、クライアントに公開します。

swagger-uiは、Swagger specを取得して、それを基にリファレンスを生成するWebクライアントアプリケーションです。プロジェクト直下のdist配下にあるファイルを適当なWebサーバーにホストするだけで動作します。Coffee Scriptで実装されています。

なお、SwaggerのクライアントはSwagger specさえ取得できればUIを構築できるので、サーバー側で自前でSwagger specを生成・公開する実装をしても問題なく動きます。つまり、REST APIならどの言語/フレームワークで実装されていてもSwaggerのクライアントを利用することができます。まだ試していませんが、swagger-codegenを利用すると、node.jsやSinatra用にSwaggerに対応したプロジェクトテンプレートをジェネレートできるようです。

scalatra-swagger

Scalatraは、2.2からScalatraでSwaggerをサポートするためのライブラリであるscalatra-swaggerを提供しています。今回はscalatra-swaggerを利用して、Scalatraで作成したREST APIのドキュメントを生成してみました。

開発環境

今回の開発環境は以下の通りです。

OSX Mountain Lion
Scala 2.9.2
sbt 0.12.2
giter8 0.4.5

Scalatraアプリの作成

ではまず、Scalatraで適当なREST APIを作成します。

giter8でScalatraプロジェクトのテンプレートを作成します。

$ g8 scalatra/scalatra-sbt

今回のプロジェクトの設定は以下のようにしました。

organization [com.example]: jp.classmethod
package [com.example.myapp]: jp.classmethod.scalatraswagger
name [My Scalatra Web App]: scalatra-swagger-sample
servlet_name [MyServlet]: SwaggerTestController
version [0.1.0-SNAPSHOT]:

作成したプロジェクトのディレクトリに移動します。

$ cd scalatra-swagger-sample/

ビルドの設定

sbtを起動する前に、sbtのバージョンとライブラリの依存性の設定を変更します。

sbtは0.12.2を使います。

build.properties

sbt.version=0.12.2

Scalatraは現在最新の2.2.0を使用しますので、バージョンを変更します。さらに、JSONライブラリとしてscalatra-jsonとjson4s-jacksonを追加します。最後に、Swagger本体であるswagger-coreと、ScalatraでSwaggerを扱うためのscalatra-swaggerを追加します。

build.sbt

organization := "jp.classmethod"

name := "scalatra-swagger-sample"

version := "0.1.0-SNAPSHOT"

scalaVersion := "2.9.2"

seq(webSettings :_*)

classpathTypes ~= (_ + "orbit")

resolvers += "Typesafe repository" at "http://repo.typesafe.com/typesafe/releases/"

libraryDependencies ++= Seq(
  "org.scalatra" % "scalatra" % "2.2.0",
  "org.scalatra" % "scalatra-scalate" % "2.2.0",
  "org.scalatra" % "scalatra-specs2" % "2.2.0" % "test",
  "org.scalatra" % "scalatra-json" % "2.2.0",
  "org.scalatra" % "scalatra-swagger"  % "2.2.0",
  "org.json4s" %% "json4s-jackson" % "3.1.0",
  "com.wordnik" % "swagger-core_2.9.1" % "1.2.0",
  "ch.qos.logback" % "logback-classic" % "1.0.6" % "runtime",
  "org.eclipse.jetty" % "jetty-webapp" % "8.1.7.v20120910" % "container;test",
  "org.eclipse.jetty.orbit" % "javax.servlet" % "3.0.0.v201112011016" % "container;provided;test" artifacts (Artifact("javax.servlet", "jar", "jar"))
)

ビルドの準備ができたのでsbtを起動します。