このエントリは以下のエントリをベースにしています。
This entry is based on the following written by Tim Quinn (Oracle).
https://medium.com/oracledevs/project-helidon-and-openapi-54a1fadc75b1

Helidon 1.1.1以後、SE/MPともOpenAPIをサポートしており、MPではMicroProfile OpenAPI仕様をサポートしています。

Helidon
https://helidon.io/
OpenAPI Specification
https://github.com/OAI/OpenAPI-Specification
MicroProfile
https://microprofile.io/
MicroProfile OpenAPI Specification
https://github.com/eclipse/microprofile-open-api

SE、MPの両方に対し、OpenAPI機能の利用方法を説明したドキュメントとサンプルコードを用意しています。

OpenAPI support in Helidon SE
https://helidon.io/docs/latest/index.html#/openapi/01_openapi
Helidon SE OpenAPI Example
https://github.com/oracle/helidon/tree/master/examples/openapi
OpenAPI support in Helidon MP
https://helidon.io/docs/latest/index.html#/microprofile/08_openapi
Helidon MP Basic OpenAPI Example
https://github.com/oracle/helidon/tree/master/examples/microprofile/openapi-basic

このエントリではOpenAPIのサポートをHelidonで作成したアプリケーションに追加する最もシンプルな方法をご紹介します。

変更点はMP、SEいずれを使っているかで変わりますので、それぞれ分けて説明します。アプリケーションのOpenAPIドキュメントにアクセスする方法は同じなので、それはひとまとめにして最後に記載します。

Helidon MPの場合

Update your pom.xml

OpenAPI関連のアノテーションのスキャン高速化のため、Jandexインデックスを作成します。セクションに以下を追加します。

<plugin>
    <groupId>org.jboss.jandex</groupId>
    <artifactId>jandex-maven-plugin</artifactId>
    <version>1.0.6</version>
    <executions>
      <execution>
          <id>make-index</id>
          <goals>
              <goal>jandex</goal>
          </goals>
      </execution>
    </executions>
</plugin>

依存関係を追加すると、OpenAPIアノテーションを利用できます。アプリケーションの実行時にHelidon OpenAPIランタイム（およびMicroProfile 2.2に対するHelidonのその他のサポート）が存在するようにします。

<dependency>
    <groupId>org.eclipse.microprofile.openapi</groupId>
    <artifactId>microprofile-openapi-api</artifactId>
    <version>1.1.2</version>
</dependency
<dependency>
    <groupId>io.helidon.microprofile.bundles</groupId>
    <artifactId>helidon-microprofile-2.2</artifactId>
    <version>1.1.2</version>
</dependency>

Annotate the endpoints

OpenAPIのアノテーションをアプリケーションのエンドポイントに追加します。以下の例はシンプルなGETエンドポイントにOpenAPIアノテーションを付加しています。

@GET
@Operation(
    summary = "Returns a generic greeting",
    description = "Greets the user generically")
@APIResponse(
    description = "Simple JSON containing the greeting",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = GreetingMessage.class)))
@Produces(MediaType.APPLICATION_JSON)
public JsonObject getDefaultMessage() {...}

@Operationと@APIResponse は新規のアノテーションです。

Helidon SEの場合

SEにおけるOpenAPIのサポートは、基本的にMPと同じですが、SEはアノテーションの処理を含んでいません。そのため、OpenAPIはエンドポイントの情報を収集するためにアノテーションに依存できません。

その代わりに、SEで作成したアプリケーションにはアプリケーションのエンドポイントを記載したOpenAPIドキュメントの静的ファイルを含めることになるでしょう。

Update your pom.xml

依存関係を追加します。

<dependency>
     <groupId>io.helidon.openapi</groupId>
     <artifactId>helidon-openapi</artifactId>
     <version>1.1.2</version>
</dependency>

Register OpenAPISupport in your code

SEで作成したアプリケーションにはすでに以下のようなコードが含まれているはずです。OpenAPISupportを登録するために1行追加します。

Config config = Config.create();
...
return Routing.builder()
         .register(JsonSupport.create())
         .register(OpenAPISupport.create(config))
         .register(health)
         .register(metrics)
         .register("/greet", greetService)
         .build();

Add a static OpenAPI document file

Swaggerのようなツールを使って、アプリケーションのAPIを記述し、OpenAPIドキュメントファイルを生成しましょう。もしくは手作業でファイルを作成、編集することも可能です。ファイルができたら、プロジェクトのMETA-INF/openapi.ymlとして追加すれば、HelidonのOpenAPIサポート機能が自動検知してくれます（訳注：META-INF/openapi.yml以外には、META-INF/openapi.yamlもしくはMETA-INF/openapi.jsonとして追加できます）。

Access ths OpenAPI document

変更してアプリケーションをビルド後、実行してみましょう。自動的にサポートされる/openapiエンドポイントに対してGETリクエストを投げてください。上記のソースコードでエンドポイントにアノテーションで付加した情報を含む多数の情報を確認できます（訳注：OpenAPI 3ベースでした）。

paths:
  /greet:
    get:
      summary: Returns a generic greeting
      description: Greets the user generically
      responses:
        default:
          description: Simple JSON containing the greeting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GreetingMessage'

What next?

これはほんの初歩的なものにすぎないので、例えばMPとSEのアプリケーションに、エンドポイントのOpenAPIモデルにプログラムで追加したり変更したり（つまりモデルのReaderとFilter）するコードを含めてみてもよいでしょう。

実のところ、HelidonのOpenAPIサポートでは、これらのソースすべてからのエンドポイント情報を組み合わせます。

• 静的ファイル
• アノテーション（MPのみ）
• configurationの設定
• model reader
• model filter