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）からダウンロードできます。

f:id:jian-feng:20190513104224j:plain — サンプルアプリの構造

Swagger UIとCamel REST DSL

Swagger とは、RESTful APIのドキュメントや、サーバ、クライアントコード、エディタ、またそれらを扱うための仕様などを提供するフレームワークであります。
Swagger UI とは、Swagger Specificationから動的にドキュメントを生成するツールです。
RES DSL とは、CamelルートでREST APIを記述するDSLです。

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

今回は、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

f:id:jian-feng:20190513113646p:plain — swagger-ui

サンプルの設定内容

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情報も意識して埋め込めば簡単に情報共有できます。このため、開発標準の一環として取り入れてください。