3.7. MicroProfile OpenAPI の管理

3.7.1. MicroProfile OpenAPI の有効化

microprofile-openapi-smallrye サブシステムは、standalone-microprofile.xml 設定で提供されます。しかし、JBoss EAP XP はデフォルトで standalone.xml を使用します。使用するには、standalone.xml にサブシステムを含める必要があります。

または、Updating standalone configurations with MicroProfile subsystems and extensions の手順に従い、standalone.xml 設定ファイルを更新できます。

手順

  1. JBoss EAP で MicroProfile OpenAPI smallrye 拡張を有効にします。 

    /extension=org.wildfly.extension.microprofile.openapi-smallrye:add()

  2. 以下の管理コマンドを使用して microprofile-openapi-smallrye サブシステムを有効にします。 

    /subsystem=microprofile-openapi-smallrye:add()

  3. サーバーをリロードします。 

    reload

microprofile-openapi-smallrye サブシステムが有効化されます。

3.7.2. Accept HTTP ヘッダーを使用した MicroProfile OpenAPI ドキュメントリクエスト

Accept HTTP ヘッダーを使用してデプロイメントから MicroProfile OpenAPI ドキュメントをリクエストします。

デフォルトでは、OpenAPI エンドポイントはで YAML ドキュメントを返します。

前提条件

  • クエリーされるデプロイメントは、MicroProfile OpenAPI ドキュメントを返すように設定されます。

手順

  • 以下の curl コマンドを実行して、デプロイメントの /openapi エンドポイントをクエリーします。 

    $ curl -v -H'Accept: application/json' http://localhost:8080/openapi
< HTTP/1.1 200 OK
...
{"openapi": "3.0.1" ... }

    http://localhost:8080 を、デプロイメントの URL およびポートに置き換えます。

    Accept ヘッダーは、JSON ドキュメントが application/json 文字列を使用して返されることを示します。

3.7.3. HTTP パラメーターを使用した MicroProfile OpenAPI ドキュメントのリクエスト

HTTP リクエストでクエリーパラメーターを使用してデプロイメントから MicroProfile OpenAPI ドキュメントを JSON 形式でリクエストします。

デフォルトでは、OpenAPI エンドポイントはで YAML ドキュメントを返します。

前提条件

  • クエリーされるデプロイメントは、MicroProfile OpenAPI ドキュメントを返すように設定されます。

手順

  • 以下の curl コマンドを実行して、デプロイメントの /openapi エンドポイントをクエリーします。 

    $ curl -v http://localhost:8080/openapi?format=JSON
< HTTP/1.1 200 OK
...

    http://localhost:8080 を、デプロイメントの URL およびポートに置き換えます。

    HTTP パラメーターの format=JSON は JSON ドキュメントが返されることを示します。

3.7.4. 静的 OpenAPI ドキュメントを提供するよう JBoss EAP を設定

ホストの REST サービスを記述する静的 OpenAPI ドキュメントに対応するように JBoss EAP を設定します。

JBoss EAP が静的 OpenAPI ドキュメントを提供するよう設定されている場合、静的 OpenAPI ドキュメントは Jakarta RESTful Web Services および MicroProfile OpenAPI アノテーションの前に処理されます。

実稼働環境では、静的ドキュメントを提供するときにアノテーション処理を無効にします。アノテーション処理を無効にすると、イミュータブルでバージョン付けできない API コントラクトがクライアントで利用可能になります。

手順

  1. アプリケーションソースツリーにディレクトリーを作成します。 

    $ mkdir APPLICATION_ROOT/src/main/webapp/META-INF

    APPLICATION_ROOT は、アプリケーションの pom.xml 設定ファイルが含まれるディレクトリーです。

  2. OpenAPI エンドポイントをクエリーし、出力をファイルにリダイレクトします。 

    $ curl http://localhost:8080/openapi?format=JSON > src/main/webapp/META-INF/openapi.json

    デフォルトでは、エンドポイントは YAML ドキュメントを提供し、format=JSON は JSON ドキュメントを返すことを指定します。

  3. OpenAPI ドキュメントモデルの処理時にアノテーションのスキャンを省略するようにアプリケーションを設定します。 

    $ echo "mp.openapi.scan.disable=true" > APPLICATION_ROOT/src/main/webapp/META-INF/microprofile-config.properties

  4. アプリケーションをリビルドします。 

    $ mvn clean install

  5. 以下の管理 CLI コマンドを使用してアプリケーションを再度デプロイします。

    1. アプリケーションのアンデプロイ: 

      undeploy microprofile-openapi.war

    2. アプリケーションのデプロイ: 

      deploy APPLICATION_ROOT/target/microprofile-openapi.war

JBoss EAP は OpenAPI エンドポイントで静的 OpenAPI ドキュメントを提供するようになりました。

3.7.5. microprofile-openapi-smallrye の無効化

管理 CLI を使用すると、JBoss EAP XP の microprofile-openapi-smallrye サブシステムを無効にすることができます。

手順

  • microprofile-openapi-smallrye サブシステムを無効にします。 

    /subsystem=microprofile-openapi-smallrye:remove()