MicroProfile OpenAPIでドキュメント生成入門
JAX-RSにMicroProfile OpenAPIでアノテーションすると、勝手に文書作成してくれるそうなので是非やりたいと思ったのだが、かなり敷居が高い。右も左もわからないところに以下の説明を見つけた。
- RESTful API (JAX-RS) 書くだけで仕様書も 自動で作られていく話 with MicroProfile Open API
- Eclipse MicroProfile OpenAPI を試してみた with WildFly Swarm
この方が簡単なサンプルを作ってくれているので、試してみる。何もわからないままでもほぼすぐに体験できる。
実行環境
- Windows7 64bit
- AdoptOpenJDK12
- Apache Maven 3.6.1
- 先のサンプル
順に見ていく
Mavenのインストール
Javaは動作しているものとする。ふだんはGradleしか使っていないので、まずMavenをインストールする。単純だ。
Downloading Apache Maven 3.6.1に行き、zipなりをダウンロード・解凍し、適当な場所に置き、そのbinフォルダにパスを通す。
コマンドプロンプトで「mvn -v」と入力して「Apache Maven 3.6.1云々」と表示されればよい。
サンプルのダウンロード
https://github.com/sightseeker/wildfly-swarm-mp-demoに行き、「Clone or Download」ボタンからzipでダウンロードを選択、解凍する。
ビルド
コマンドプロンプトで解凍したディレクトリに行き、「mvn clean package」とする。このとき相当な量のダウンロードが行われるようで、結構時間がかかる。このマシンで3分程度だ。
ダウンロードされるライブラリ等は「c:\users\ユーザ名.m2」フォルダに格納される。
実行
「WildFly Swarm」という名称が「Throntail」という名称に変更されたようで、ビルド後の生成物が説明とは違っており、実行すべきjarファイルも異なる。
java -jar target/demo-swarm.jar
と説明にはあるが、実際には
java -jar target/demo-thorntail.jar
になる。起動完了すると、「Thorntail is Ready」と表示される。
使ってみる
説明にあるように、以下のURLにアクセスする。
- http://localhost:8080/api/hello
これは何も表示されなかった。 - http://localhost:8080/openapi
YAMLドキュメントがダウンロードできる。 - http://localhost:8080/
以下のようなドキュメントが表示される。
とりあえず成功だ。