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>
全ソースコード