原文はこちら。
The original article was written by Suren Konathala (Director of Engineering, HeroDigital).
https://medium.com/helidon/helidon-with-swagger-openapi-182ab670c2ae
https://www.surenk.com/blog/helidon-with-swagger
Swagger UIは（Javaベースの）APIドキュメントを生成、表示するための素晴らしいリソースです。Swagger UIをMavenベースのプロジェクトに追加するのは、クラスにいくつかのアノテーションを追加し、pom.xmlにいくつかの依存関係を追加するだけの簡単な作業ですが、Helidonで構築したプロジェクトにはいくつかのステップがあることがわかりました。この記事ではその詳細を紹介します。
【訳注】原文執筆時の最新版は2.3.4のため、この記事ではHelidon MP 2.3.4を使っています（2021/11/05現在の最新版は2.4.0）。
TL;DR
この記事では、Helidon MPで作成されたプロジェクトにSwagger UIをセットアップする方法を説明します。動作するサンプルはGitHubにて公開しています。
Helidon MP Quickstart
https://helidon.io/docs/latest/#/mp/guides/02_quickstart
Helidon MP With Swagger Example
https://github.com/ksurendra/helidon-mp-swagger
Why this post?
Helidon MPで作成したAPIのみのプロジェクトにSwagger UIをセットアップするのに時間がかかったためです。この記事を仲間の開発者に共有し時間を節約してもらいたいと願っています。
Getting started
Building from scratch
既存のプロジェクトがある場合には、手順1と2は省略できます。
1. Helidon MPのarchetypeを使い、新規プロジェクトを作成します。
mvn -U archetype:generate \
-DinteractiveMode=false \
-DarchetypeGroupId=io.helidon.archetypes \
-DarchetypeArtifactId=helidon-quickstart-mp \
-DarchetypeVersion=2.3.4 \
-DgroupId=io.helidon.examples \
-DartifactId=helidon-quickstart-mp \
-Dpackage=io.helidon.examples.quickstart.mp
2. デフォルトプロジェクトをビルド、実行します。
mvn package
java -jar ./target/helidon-quickstart-mp.jar
3.以下の依存関係をpom.xmlに追加します。
<dependency>
<groupId>org.eclipse.microprofile.openapi</groupId>
<artifactId>microprofile-openapi-api</artifactId>
<version>1.2</version>
</dependency><!-- NOTE: I built the project using Helidon MP 2.3.4, please use the version per your project -->
<dependency>
<groupId>io.helidon.microprofile.openapi</groupId>
<artifactId>helidon-microprofile-openapi</artifactId>
<version>2.3.4</version>
</dependency><dependency>
<groupId>org.microprofile-ext.openapi-ext</groupId>
<artifactId>openapi-ui</artifactId>
<version>1.1.5</version>
</dependency>
4. 再度プロジェクトをビルド、実行します。
mvn package
java -jar ./target/helidon-quickstart-mp.jar
5. Webブラウザで、openapi-ui というURLを使います。デフォルトではURLは http://localhost:9393/openapi-ui のようになります（訳注: 原文では9393です）。
以上です。
Adding docs to your APIs
ドキュメント生成に必要なアノテーションを追加する必要があります。以下はその例です（ファイルはこちら）。
@Path("/greeting")
@PUT
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@RequestBody(name = "greeting",
required = true,
content = @Content(mediaType = "application/json",
schema = @Schema(type = SchemaType.STRING, example = "{\"greeting\" : \"Hola\"}")))
@APIResponses({
@APIResponse(name = "normal", responseCode = "204", description = "Greeting updated"),
@APIResponse(name = "missing 'greeting'", responseCode = "400",
description = "JSON did not contain setting for 'greeting'")})
public Response updateGreeting(JsonObject jsonObject) { ... }
Background
Swagger-uiの依存性を利用せず、Open-APIを利用していることにお気づきでしょうか。Helidon MPでビルドしたプロジェクトにMicroProfile OpenAPIアノテーションを追加すると、Helidonが自動的にOpenAPIドキュメントを生成し、クライアントがアクセス可能なエンドポイントを提供します。
詳細は以下をご覧ください。
Project Helidon and OpenAPI
https://medium.com/helidon/project-helidon-and-openapi-54a1fadc75b1
https://logico-jp.io/2019/06/19/project-helidon-and-openapi/
OpenAPI Specifications
https://swagger.io/specification/
microprofile-extensions / openapi-ext
https://github.com/microprofile-extensions/openapi-ext/tree/main/openapi-ui
Helidon SE OpenAPI Example
https://github.com/oracle/helidon/tree/master/examples/openapi
Resources
この記事で使ったサンプル
https://github.com/ksurendra/helidon-mp-swagger
Helidon: Java Libraries for Microservices
https://github.com/oracle/helidon
Swagger documentation
https://swagger.io/docs/
Logico Inside 