こんにちは。平田です。
JBoss EAP 7を使って、JAX-RSアプリケーションからSwagger仕様を生成してみます。
SwaggerはREST APIのインタフェース定義の標準（SOAPにおけるWSDLのような）です。JSONかYAMLで記述します。Swagger自体は仕様であり、仕様に基いて様々なツールが開発されています。
今回は、swagger-coreを用いてJAX-RSのリソースクラスからSwagger仕様（JSON形式のREST APIインタフェース定義）を生成し、その仕様をswagger-uiで表示してみます。
swagger-core
EAP7に同梱されているJAX-RSとJSFのサンプルであるkitchensinkをコピーします。
$ cd path/to/jboss-eap-7.0.0.GA-quickstarts $ cp -R kitchensink kitchensink-swagger
swagger-coreのライブラリをpom.xmlに指定します。swagger-coreのセットアップ手順によれば、JAX-RS 2.0に対応するのはswagger-jersey2-jaxrsのようですが、これを試したところデプロイ時にjerseyのクラスに起因するエラーが出たため、今回はswagger-jaxrsとしました。
pom.xmlを編集 <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-jaxrs</artifactId> <version>1.5.9</version> </dependency>
次にswagger-coreの設定を行います。セットアップ手順によればweb.xmlで宣言する方法と、APIを叩く方法があります。ここではAPIを使います。kitchensinkサンプルのJaxRsActivator.javaを編集し、初期化コード（コンストラクタ）を追記します。
public JaxRsActivator() {
new BeanConfig() {{
setBasePath("/jboss-kitchensink-swagger/rest");
setResourcePackage("org.jboss.as.quickstarts.kitchensink.rest");
}}.setScan();
}BeanConfigクラスは一見するとただのJava Beanっぽいのですが、setScan（もしくはsetScan(true)）することでSwagger仕様が生成されるようになります。
続いてJAX-RSのリソースクラスに、swagger-coreのアノテーションを付与します。
@Path("/members")
@Api // <-@Apiを追加
@RequestScoped
public class MemberResourceRESTService {
...ここでは@Apiのみ付与していますが、説明などを追加するためのアノテーションが用意されています。
この時点でSwagger仕様を生成できます。デプロイして確認してみます。まずEAP7を起動します。
$ cd $JBOSS_HOME/bin $ ./standalone.sh
kitchensink-swaggerをビルド、デプロイするとSwagger仕様にアクセスできるようになります。
$ mvn -Dmaven.test.skip=true clean package wildfly:deploy
$ curl -s http://localhost:8080/jboss-kitchensink-swagger/rest/swagger.json | python -mjson.tool
{
"basePath": "/jboss-kitchensink-swagger/rest",
"definitions": {
"Member": {
"properties": {
"email": {
"type": "string"
},
"id": {
"format": "int64",
"type": "integer"
},
...swagger-ui
swagger-uiは、Swagger仕様を読みやすく表示するフロントエンドで、APIを叩くUIも備えています。
swagger-ui自体はHTML、CSS、JavaScriptで構成されており、ブラウザで開くだけ動きます。今回はWARファイルに埋め込んでみます。
配布ページからswagger-uiの最新ビルド（この記事を書いている時点では2.1.4）をダウンロードし、distディレクトリごとコピーします。
$ tar zxvf swagger-ui-2.1.4.tar.gz $ cp -R swagger-ui-2.1.4/dist path/to/jboss-eap-7.0.0.GA-quickstarts/kitchensink-swagger/src/main/webapp/swagger-ui
次にswagger-uiのファイルを一部修正します。初期状態ではSwaggerのサンプルAPIの情報が表示されます。これは、サンプルAPIのSwagger仕様のURLがHTMLファイルにハードコーディングされているためです。この状態でもswagger-ui画面からSwagger仕様のURLを指定することで任意のAPI仕様を表示できますが、不便なので修正します。
// src/main/webapp/swagger-ui/index.htmlを編集
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
// url = "http://petstore.swagger.io/v2/swagger.json";
url = "http://localhost:8080/jboss-kitchensink-swagger/rest/swagger.json"; // <- アプリケーション内のSwagger仕様のURLを指定する
}再ビルド、デプロイします。
$ mvn -Dmaven.test.skip=true clean package wildfly:deploy
ブラウザでhttp://localhost:8080/jboss-kitchensink/swagger-uiを開くと、swagger-uiの画面が開きます。Expand Operationsという部分をクリックすると、REST APIの詳細が開きます。
各APIのTry it out!ボタンを押すとAPIを叩けます。
REST APIを開発する場合、APIのインタフェース仕様をAPIのクライアントに提供するのですが、標準化されたインタフェース定義やツールを使うと相互運用性が上がって良さそうですね。