3.7. Eclipse MicroProfile OpenAPI 管理
3.7.1. Eclipse MicroProfile OpenAPI の有効化
microprofile-openapi-smallrye サブシステムは、standalone-microprofile.xml 設定で提供されます。しかし、JBoss EAP XP はデフォルトで standalone.xml を使用します。使用するには、standalone.xml にサブシステムを含める必要があります。
または、Updating standalone configurations with Eclipse MicroProfile subsystems and extensions の手順に従い、standalone.xml 設定ファイルを更新できます。
手順
JBoss EAP で MicroProfile OpenAPI smallrye 拡張を有効にします。
/extension=org.wildfly.extension.microprofile.openapi-smallrye:add()
以下の管理コマンドを使用して
microprofile-openapi-smallryeサブシステムを有効にします。/subsystem=microprofile-openapi-smallrye:add()
サーバーをリロードします。
reload
microprofile-openapi-smallrye サブシステムが有効化されます。
3.7.2. Accept HTTP ヘッダーを使用した Eclipse MicroProfile OpenAPI ドキュメントリクエスト
Accept HTTP ヘッダーを使用してデプロイメントから Eclipse MicroProfile OpenAPI ドキュメントをリクエストします。
デフォルトでは、OpenAPI エンドポイントはで YAML ドキュメントを返します。
要件
- クエリーされるデプロイメントは、Eclipse 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 パラメーターを使用した Eclipse MicroProfile OpenAPI ドキュメントのリクエスト
HTTP リクエストでクエリーパラメーターを使用してデプロイメントから Eclipse MicroProfile OpenAPI ドキュメントを JSON 形式でリクエストします。
デフォルトでは、OpenAPI エンドポイントはで YAML ドキュメントを返します。
要件
- クエリーされるデプロイメントは、Eclipse 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 ドキュメントは JAX-RS および MicroProfile OpenAPI アノテーションの前に処理されます。
実稼働環境では、静的ドキュメントを提供するときにアノテーション処理を無効にします。アノテーション処理を無効にすると、イミュータブルでバージョン付けできない API コントラクトがクライアントで利用可能になります。
手順
アプリケーションソースツリーにディレクトリーを作成します。
$ mkdir APPLICATION_ROOT/src/main/webapp/META-INFAPPLICATION_ROOT は、アプリケーションの
pom.xml設定ファイルが含まれるディレクトリーです。OpenAPI エンドポイントをクエリーし、出力をファイルにリダイレクトします。
$ curl http://localhost:8080/openapi?format=JSON > src/main/webapp/META-INF/openapi.json
デフォルトでは、エンドポイントは YAML ドキュメントを提供し、
format=JSONは JSON ドキュメントを返すことを指定します。OpenAPI ドキュメントモデルの処理時にアノテーションのスキャンを省略するようにアプリケーションを設定します。
$ echo "mp.openapi.scan.disable=true" > APPLICATION_ROOT/src/main/webapp/META-INF/microprofile-config.propertiesアプリケーションをリビルドします。
$ mvn clean install
以下の管理 CLI コマンドを使用してアプリケーションを再度デプロイします。
アプリケーションのアンデプロイ:
undeploy microprofile-openapi.war
アプリケーションのデプロイ:
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()
