4.7. MicroProfile OpenAPI アプリケーションの開発
4.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
設定ファイルを更新できます。
手順
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
サブシステムが有効化されます。
4.7.2. MicroProfile OpenAPI の Maven プロジェクトの設定
Maven プロジェクトを作成し、MicroProfile OpenAPI アプリケーションを作成するための依存関係を設定します。
前提条件
- Maven がインストールされている。
- JBoss EAP Maven リポジトリーが設定されている。
手順
プロジェクトを初期化します。
mvn archetype:generate \ -DgroupId=com.example.microprofile.openapi \ -DartifactId=microprofile-openapi\ -DarchetypeGroupId=org.apache.maven.archetypes \ -DarchetypeArtifactId=maven-archetype-webapp \ -DinteractiveMode=false cd microprofile-openapi
このコマンドは、プロジェクトのディレクトリー構造と
pom.xml
設定ファイルを作成します。pom.xml
設定ファイルを編集して以下を追加します。<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example.microprofile.openapi</groupId> <artifactId>microprofile-openapi</artifactId> <version>1.0-SNAPSHOT</version> <packaging>war</packaging> <name>microprofile-openapi Maven Webapp</name> <!-- Update the value with the URL of the project --> <url>http://www.example.com</url> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> <version.server.bom>3.0.0.GA</version.server.bom> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.jboss.bom</groupId> <artifactId>jboss-eap-xp-microprofile</artifactId> <version>${version.server.bom}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.jboss.spec.javax.ws.rs</groupId> <artifactId>jboss-jaxrs-api_2.1_spec</artifactId> <scope>provided</scope> </dependency> </dependencies> <build> <!-- Set the name of the archive --> <finalName>${project.artifactId}</finalName> <plugins> <plugin> <artifactId>maven-clean-plugin</artifactId> <version>3.1.0</version> </plugin> <!-- see http://maven.apache.org/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_war_packaging --> <plugin> <artifactId>maven-resources-plugin</artifactId> <version>3.0.2</version> </plugin> <plugin> <artifactId>maven-compiler-plugin</artifactId> <version>3.8.0</version> </plugin> <plugin> <artifactId>maven-surefire-plugin</artifactId> <version>2.22.1</version> </plugin> <plugin> <artifactId>maven-war-plugin</artifactId> <version>3.2.2</version> </plugin> <plugin> <artifactId>maven-install-plugin</artifactId> <version>2.5.2</version> </plugin> <plugin> <artifactId>maven-deploy-plugin</artifactId> <version>2.8.2</version> </plugin> <!-- Allows to use mvn wildfly:deploy --> <plugin> <groupId>org.wildfly.plugins</groupId> <artifactId>wildfly-maven-plugin</artifactId> </plugin> </plugins> </build> </project>
pom.xml
設定ファイルおよびディレクトリー構造を使用してアプリケーションを作成します。
関連情報
- JBoss EAP Maven リポジトリーの設定に関する詳細は、POM ファイルを使用した JBoss EAP Maven リポジトリーの設定 を参照してください。
4.7.3. MicroProfile OpenAPI アプリケーションの開発
OpenAPI v3 ドキュメントを返すアプリケーションを作成します。
前提条件
- Maven プロジェクトは、MicroProfile OpenAPI アプリケーションを作成するために設定されます。
手順
クラスファイルを保存するディレクトリーを作成します。
$ mkdir -p APPLICATION_ROOT/src/main/java/com/example/microprofile/openapi/
APPLICATION_ROOT は、アプリケーションの
pom.xml
設定ファイルが含まれるディレクトリーです。新しいディレクトリーに移動します。
$ cd APPLICATION_ROOT/src/main/java/com/example/microprofile/openapi/
以下の手順のクラスファイルすべては、このディレクトリーに作成する必要があります。
以下の内容でクラスファイル
InventoryApplication.java
を作成します。package com.example.microprofile.openapi; import javax.ws.rs.ApplicationPath; import javax.ws.rs.core.Application; @ApplicationPath("/inventory") public class InventoryApplication extends Application { }
このクラスはアプリケーションの REST エンドポイントとして機能します。
以下の内容でクラスファイル
Fruit.java
を作成します。package com.example.microprofile.openapi; public class Fruit { private final String name; private final String description; public Fruit(String name, String description) { this.name = name; this.description = description; } public String getName() { return this.name; } public String getDescription() { return this.description; } }
以下の内容でクラスファイル
FruitResource.java
を作成します。package com.example.microprofile.openapi; import java.util.Collections; import java.util.LinkedHashMap; import java.util.Set; import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.Path; import javax.ws.rs.Produces; import javax.ws.rs.core.MediaType; @Path("/fruit") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) public class FruitResource { private final Set<Fruit> fruits = Collections.newSetFromMap(Collections.synchronizedMap(new LinkedHashMap<>())); public FruitResource() { this.fruits.add(new Fruit("Apple", "Winter fruit")); this.fruits.add(new Fruit("Pineapple", "Tropical fruit")); } @GET public Set<Fruit> all() { return this.fruits; } @POST public Set<Fruit> add(Fruit fruit) { this.fruits.add(fruit); return this.fruits; } @DELETE public Set<Fruit> remove(Fruit fruit) { this.fruits.removeIf(existingFruit -> existingFruit.getName().contentEquals(fruit.getName())); return this.fruits; } }
アプリケーションの root ディレクトリーに移動します。
$ cd APPLICATION_ROOT
以下の Maven コマンドを使用してアプリケーションをビルドおよびデプロイします。
$ mvn wildfly:deploy
アプリケーションをテストします。
curl
を使用して、サンプルアプリケーションの OpenAPI ドキュメントにアクセスします。$ curl http://localhost:8080/openapi
以下の出力が返されます。
openapi: 3.0.1 info: title: Archetype Created Web Application version: "1.0" servers: - url: /microprofile-openapi paths: /inventory/fruit: get: responses: "200": description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/Fruit' post: requestBody: content: application/json: schema: $ref: '#/components/schemas/Fruit' responses: "200": description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/Fruit' delete: requestBody: content: application/json: schema: $ref: '#/components/schemas/Fruit' responses: "200": description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/Fruit' components: schemas: Fruit: type: object properties: description: type: string name: type: string
関連情報
- MicroProfile SmallRye OpenAPI で定義されたアノテーションの一覧は、MicroProfile OpenAPI annotations を参照してください。
4.7.4. 静的 OpenAPI ドキュメントを提供するよう JBoss EAP を設定
ホストの REST サービスを記述する静的 OpenAPI ドキュメントに対応するように JBoss EAP を設定します。
JBoss EAP が静的 OpenAPI ドキュメントを提供するよう設定されている場合、静的 OpenAPI ドキュメントは Jakarta RESTful Web Services および MicroProfile OpenAPI アノテーションの前に処理されます。
実稼働環境では、静的ドキュメントを提供するときにアノテーション処理を無効にします。アノテーション処理を無効にすると、イミュータブルでバージョン付けできない API コントラクトがクライアントで利用可能になります。
手順
アプリケーションソースツリーにディレクトリーを作成します。
$ mkdir APPLICATION_ROOT/src/main/webapp/META-INF
APPLICATION_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 ドキュメントを提供するようになりました。