4.7. Eclipse MicroProfile OpenAPI アプリケーションの開発

4.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 サブシステムが有効化されます。

4.7.2. Eclipse MicroProfile OpenAPI の Maven プロジェクトの設定

Maven プロジェクトを作成し、Eclipse MicroProfile OpenAPI アプリケーションを作成するための依存関係を設定します。

要件

Maven がインストールされている。
JBoss EAP Maven リポジトリーが設定されている。
JBoss EAP Maven リポジトリーの設定に関する詳細は、POM ファイルを使用した 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>1.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 設定ファイルおよびディレクトリー構造を使用してアプリケーションを作成します。

4.7.3. Eclipse MicroProfile OpenAPI アプリケーションの作成

OpenAPI v3 ドキュメントを返すアプリケーションを作成します。

要件

Maven プロジェクトは、Eclipse 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 ドキュメントは JAX-RS および 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 コマンドを使用してアプリケーションを再度デプロイします。
1. アプリケーションのアンデプロイ:
```
undeploy microprofile-openapi.war
```
2. アプリケーションのデプロイ:
```
deploy APPLICATION_ROOT/target/microprofile-openapi.war
```

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

4.7. Eclipse MicroProfile OpenAPI アプリケーションの開発

4.7.1. Eclipse MicroProfile OpenAPI の有効化

4.7.2. Eclipse MicroProfile OpenAPI の Maven プロジェクトの設定

4.7.3. Eclipse MicroProfile OpenAPI アプリケーションの作成

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

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Red Hat legal and privacy links

Red Hat legal and privacy links