主页
产品
Red Hat JBoss Enterprise Application Platform
7.4
使用 JBoss EAP XP 4.0.0
4.7. 开发 MicroProfile OpenAPI 应用

4.7. 开发 MicroProfile OpenAPI 应用

4.7.1. 启用 MicroProfile OpenAPI
复制链接

microprofile-openapi-smallrye 子系统在 standalone-microprofile.xml 配置中提供。但是，JBoss EAP XP 默认使用 standalone.xml。您必须在 standalone.xml 中包含子系统才能使用它。

或者，您可以按照使用 MicroProfile 子系统和扩展更新独立配置的流程来更新 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>4.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. 创建 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;
    }
}

进入应用程序的根目录：
```
$ 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 注解。

4.7.4. 配置 JBoss EAP 以提供静态 OpenAPI 文档
复制链接

配置 JBoss EAP 以提供描述主机的 REST 服务的静态 OpenAPI 文档。

当 JBoss EAP 配置为提供静态 OpenAPI 文档时，将在任何 Jakarta RESTful Web 服务和 MicroProfile OpenAPI 注解之前处理静态 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. 开发 MicroProfile OpenAPI 应用

4.7.1. 启用 MicroProfile OpenAPI
复制链接

4.7.2. 为 MicroProfile OpenAPI 配置 Maven 项目
复制链接

4.7.3. 创建 MicroProfile OpenAPI 应用
复制链接

4.7.4. 配置 JBoss EAP 以提供静态 OpenAPI 文档
复制链接

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

4.7. 开发 MicroProfile OpenAPI 应用

4.7.1. 启用 MicroProfile OpenAPI复制链接链接已复制到粘贴板!

4.7.2. 为 MicroProfile OpenAPI 配置 Maven 项目复制链接链接已复制到粘贴板!

4.7.3. 创建 MicroProfile OpenAPI 应用复制链接链接已复制到粘贴板!

4.7.4. 配置 JBoss EAP 以提供静态 OpenAPI 文档复制链接链接已复制到粘贴板!

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

4.7.1. 启用 MicroProfile OpenAPI
复制链接

4.7.2. 为 MicroProfile OpenAPI 配置 Maven 项目
复制链接

4.7.3. 创建 MicroProfile OpenAPI 应用
复制链接

4.7.4. 配置 JBoss EAP 以提供静态 OpenAPI 文档
复制链接