Posted at

swagger-uiでAPIドキュメント公開方法

今回は、swagger-uiをFuseアプリケーションに埋め込み、APIドキュメント(WebAPI仕様書)を簡単に公開するサンプルと設定内容を紹介します。

このサンプルでは、Swagger UI を使用して、RES DSL で定義されたAPIのAPIドキュメント(WebAPI仕様書)を表示します。

ソースコードはGithub([https://github.com/jian-feng/camel-restdsl-swagger-demo.git])からダウンロードできます。

サンプルの構成


Swagger UIとCamel REST DSL



  • Swagger とは、RESTful APIのドキュメントや、サーバ、クライアントコード、エディタ、またそれらを扱うための仕様などを提供するフレームワークであります。


  • Swagger UI とは、Swagger Specificationから動的にドキュメントを生成するツールです。


  • RES DSL とは、CamelルートでREST APIを記述するDSLです。

因みに、REST DSLでREST APIを開発する方法は、これらの記事をご参照ください。


  1. Creating a REST API in Apache Camel

  2. Get started with REST services with Apache Camel

  3. 29行でメール送信サービスを作る - Apache Camel

今回は、REST DSL開発ではなく、主にSwagger UI連携するための設定 を説明させてください。


サンプルの実行方法

Mavenコマンドで実行します。

mvn spring-boot:run

そして、ブラウザでサンプルアプリで公開されるSwagger UIを表示できます。

http://localhost:8080/webjars/swagger-ui/3.22.0/index.html?url=/camel/api-docs

swagger-ui.png


サンプルの設定内容


Step 0. Swagger UIの組み込み

pom.xmlにSwaggerライブラリを追加します。

<!-- Swagger support for restdsl -->

<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-swagger-java-starter</artifactId>
</dependency>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>swagger-ui</artifactId>
<version>${swagger.ui.version}</version>
</dependency>


Step 1. REST Configuration

Camel提供のSwagger設定項目を使用して、API全体の概要情報をRest configuration(camel-context.xml<restConfiguration>)に記述します。

例:

<restConfiguration apiComponent="swagger"

apiContextPath="/api-docs" component="servlet"
contextPath="/camel" enableCORS="true" host="0.0.0.0" port="8080">
<dataFormatProperty key="prettyPrint" value="true"/>
<!-- 設定可能なapiProperty一覧は、Swaggerドキュメントを参照 -->
<!-- http://swagger.io/specification/#infoObject -->
<apiProperty key="api.title" value="My REST API"/>
<apiProperty key="api.version" value="1.0.0"/>
<apiProperty key="api.description" value="APIドキュメントのデモ"/>
<apiProperty key="api.contact.name" value="フェン ジン"/>
<apiProperty key="api.contact.email" value="jfeng@redhat.com"/>
</restConfiguration>



  • apiComponent , apiContextPath enableCORSは、Swagger有効化ため最低限の設定。他に設定可能な内容は、こちらを参照してください。


  • <apiProperty>は、API情報(infoObject)の設定。他に設定可能な内容は、こちらを参照してください。


Step 2. REST Context

Camel提供のSwagger設定項目を使用して、個々のAPIの詳細(例、要求/応答のデータタイプなど)をRest context(camel-context.xml<rest>)に記述します。


Rest contextを別XMLで記述し、Camel-context.xmlにてincludeすることもできます。


例:

<rest bindingMode="off" id="rest-1" path="/restsvc">

<description>sample rest service</description>
<get id="get-1" uri="/ping">
<description>This is ping service</description>
<responseMessage code="200"
message="要求情報が正常に処理され、HelloメッセージがJSON形式で返す" responseModel="org.mycompany.ResponseInfo"/>
<responseMessage code="500"
message="要求情報に問題がないが、サーバ側で処理異常のため、ErrorメッセージがJSON形式で返す" responseModel="org.mycompany.ErrorInfo"/>
<route>
<to uri="direct:hello"/>
</route>
</get>
</rest>



  • <description> , <responseMessage> は、Swagger有効化ため最低限の設定。他に設定可能な内容は、こちらを参照してください。


Step 3. DataModel

Swagger Coreのモデルプロパティ定義(@ApiModelProperty)アノテーションを使って、個々のDataModelに補足情報を追加します。

要求・応答情報のデータモデルやリソースモデル内で定義している各プロパティに @ApiModelProperty を用いて、プロパティの説明や入力例、プロパティの表示順序などを設定できます。以下は主要なメソッドを説明します。

メソッド        説明  

value プロパティ名を指定します。
required プロパティが必須かどうかを指定します。 (default: false)
example プロパティの入力例を指定します。
position プロパティの表示順序を指定します。 (default: 0)

例: src/main/java/org/mycompany/ResponseInfo.java

import io.swagger.annotations.ApiModelProperty;

public class ResponseInfo {
@ApiModelProperty(value = "Hello msg from camel", required = true, example = "sample message")
private String msg;

public String getMsg() {
return msg;
}

public void setMsg(String msg) {
this.msg = msg;
}
}


終わりに

CamelのREST DSLで開発されるAPIはcamel-swaggerを介して、APIドキュメントを公開する方法を理解できたでしょうか。APIの開発時に、ソースコード上でコメントだけでなく、公開可能なAPI情報も意識して埋め込めば簡単に情報共有できます。このため、開発標準の一環として取り入れてください。