APIドキュメントをSwaggerで簡単に用意する (Apache Camel)

Swaggerとは

json形式でAPIドキュメントを作成するというフォーマット。
UIも準備されている。

詳しくは検索してみて。

Apache Camel + Swagger

Apache Camelを使うと自前でSwaggerのjsonを書く必要がない。

サマリ

Camelで実装

サーバの初期設定 (spring用xmlで定義することも可能）

restConfiguration().component("netty4-http").bindingMode(RestBindingMode.json)
        .dataFormatProperty("prettyPrint", "true") // jsonの整形
        .contextPath("/").port(18181) // httpサーバ (netty)の設定
        .apiContextPath("/api-doc") // swagger api doc の url
        .apiProperty("api.title", "Example API") // api title
        .apiProperty("api.version", "1.2.3") // api version
        .enableCORS(true) // rest用
        .apiProperty("cors", "true"); // api doc用

RESTの定義

// user
rest("/user").description("ユーザーサービス")
        .consumes("application/json").produces("application/json")

        // HTTP GET
        .get("/{id}").description("IDからユーザー情報を取得")
        // パラメータの説明
        .param().name("id").type(path).description("取得するユーザーのID").dataType("integer").endParam()
        .to("direct:xxx")

        // HTTP POST
        .post("").description("ユーザーを新規追加")
        .param().name("body").type(body).description("").required(false).endParam()
        .to("direct:yyy")
;

このようになる

環境

• swagger ui
  • http://swagger.io/swagger-ui/
  • PCにダウンロードしたhtmlファイルをダブルクリック （特別なサーバは不要）
• APIサーバ
  • Camelで作ったもの
• swagger ui --> APIサーバ
  • swagger uiのjavascriptがajaxでアクセスする
  • camelのrest設定でcors（クロスドメイン）を許可するとブラウザがアクセスしてくれる
  • 矢印はswagger uiが直接apiサーバを呼び出しているように見えるが、単なるhtmlなのでswagger uiのjavascriptの指示によりブラウザがapiサーバにアクセスしているだけ

利用するライブラリ

pom.xml

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

全ソースコード