JBoss EAP 7でSwagger

こんにちは。平田です。

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の詳細が開きます。

swagger-ui

各APIのTry it out!ボタンを押すとAPIを叩けます。

REST APIを開発する場合、APIのインタフェース仕様をAPIのクライアントに提供するのですが、標準化されたインタフェース定義やツールを使うと相互運用性が上がって良さそうですね。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です