Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

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 配置文件。

流程

  1. 在 JBoss EAP 中启用 MicroProfile OpenAPI smallrye 扩展： 

    /extension=org.wildfly.extension.microprofile.openapi-smallrye:add()
    Copy to Clipboard Toggle word wrap

  2. 使用以下管理命令启用 microprofile-openapi-smallrye 子系统： 

    /subsystem=microprofile-openapi-smallrye:add()
    Copy to Clipboard Toggle word wrap

  3. 重新加载服务器。 

    reload
    Copy to Clipboard Toggle word wrap

microprofile-openapi-smallrye 子系统已启用。

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

创建一个 Maven 项目，以设置用于创建 MicroProfile OpenAPI 应用的依赖项。

先决条件

  • 已安装 Maven。
  • JBoss EAP Maven 存储库已配置。

流程

  1. 初始化项目： 

    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
    Copy to Clipboard Toggle word wrap

    该命令创建项目的目录结构以及 pom.xml 配置文件。

  2. 编辑 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>
    Copy to Clipboard Toggle word wrap

    使用 pom.xml 配置文件和目录结构来创建应用。

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

创建返回 OpenAPI v3 文档的应用程序。

先决条件

  • 配置了 Maven 项目以创建 MicroProfile OpenAPI 应用。

流程

  1. 创建用于存储类文件的目录： 

    $ mkdir -p APPLICATION_ROOT/src/main/java/com/example/microprofile/openapi/
    Copy to Clipboard Toggle word wrap

    APPLICATION_ROOT 是包含应用的 pom.xml 配置文件的目录。

  2. 进入新目录： 

    $ cd APPLICATION_ROOT/src/main/java/com/example/microprofile/openapi/
    Copy to Clipboard Toggle word wrap

    必须在这个目录中创建以下步骤中的所有类文件。

  3. 使用以下内容创建类文件 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 {
}
    Copy to Clipboard Toggle word wrap

    此类充当应用的 REST 端点。

  4. 使用以下内容创建一个类文件 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;
    }
}
    Copy to Clipboard Toggle word wrap

  5. 创建包含以下内容的类文件 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;
    }
}
    Copy to Clipboard Toggle word wrap

  6. 进入应用程序的根目录： 

    $ cd APPLICATION_ROOT
    Copy to Clipboard Toggle word wrap

  7. 使用以下 Maven 命令构建和部署应用程序： 

    $ mvn wildfly:deploy
    Copy to Clipboard Toggle word wrap

  8. 测试应用。

    • 使用 curl 访问示例应用程序的 OpenAPI 文档： 

      $ curl http://localhost:8080/openapi
      Copy to Clipboard Toggle word wrap

    • 返回以下输出： 

      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
      Copy to Clipboard Toggle word wrap

其它资源

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

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

当 JBoss EAP 配置为提供静态 OpenAPI 文档时，将在任何 Jakarta RESTful Web 服务和 MicroProfile OpenAPI 注解之前处理静态 OpenAPI 文档。

在生产环境中，在提供静态文档时禁用注解处理。禁用注解处理可确保客户端可以使用不可变和版本的 API 合同。

流程

  1. 在应用程序源树中创建目录： 

    $ mkdir APPLICATION_ROOT/src/main/webapp/META-INF
    Copy to Clipboard Toggle word wrap

    APPLICATION_ROOT 是包含应用的 pom.xml 配置文件的目录。

  2. 查询 OpenAPI 端点，将输出重定向到文件： 

    $ curl http://localhost:8080/openapi?format=JSON > src/main/webapp/META-INF/openapi.json
    Copy to Clipboard Toggle word wrap

    默认情况下，端点提供 YAML 文档，format=JSON 指定返回 JSON 文档。

  3. 配置应用程序，以便在处理 OpenAPI 文档模型时跳过注解扫描： 

    $ echo "mp.openapi.scan.disable=true" > APPLICATION_ROOT/src/main/webapp/META-INF/microprofile-config.properties
    Copy to Clipboard Toggle word wrap

  4. 重建应用程序： 

    $ mvn clean install
    Copy to Clipboard Toggle word wrap

  5. 使用以下管理 CLI 命令再次部署应用程序：

    1. 取消部署应用程序： 

      undeploy microprofile-openapi.war
      Copy to Clipboard Toggle word wrap

    2. 部署应用程序： 

      deploy APPLICATION_ROOT/target/microprofile-openapi.war
      Copy to Clipboard Toggle word wrap

JBoss EAP 现在在 OpenAPI 端点上提供静态 OpenAPI 文档。

Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2026 Red Hat返回顶部