配置 OpenAPI 服务 - 服务管理 | 无服务器逻辑 | Red Hat OpenShift Serverless 1.34

OpenAPI 函数定义
根据 OpenAPI 规范发送 REST 请求
配置 OpenAPI 服务的端点 URL

该OpenAPI 规范 (OAS) 定义了 HTTP API 的标准、与编程语言无关的接口。无需访问源代码、其他文档或网络流量检查，即可了解服务的各项功能。当您使用 OpenAPI 定义服务时，您可以使用最少的实现逻辑来理解和与之交互。正如接口描述简化了底层编程一样，OpenAPI 规范消除了调用服务的猜测工作。

OpenAPI 函数定义

OpenShift Serverless Logic 允许工作流使用函数中的 OpenAPI 规范引用与远程服务交互。

OpenAPI 函数定义示例

{
   "functions": [
      {
         "name": "myFunction1",
         "operation": "classpath:/myopenapi-file.yaml#myFunction1"
      }
   ]
}

operation 属性是由以下参数组成的string

URI：引擎使用此 URI 来定位规范文件，例如classpath。
操作标识符：您可以在 OpenAPI 规范文件中找到此标识符。

OpenShift Serverless Logic 支持以下 URI 方案

classpath：将其用于位于应用程序项目 src/main/resources 文件夹中的文件。classpath 是默认的 URI 方案。如果您未定义 URI 方案，则文件位置为 src/main/resources/myopenapifile.yaml。
file：将其用于位于文件系统中的文件。
http 或 https：将其用于远程位置的文件。

确保在构建时可以使用 OpenAPI 规范文件。OpenShift Serverless Logic 使用内部代码生成功能在运行时发送请求。构建应用程序镜像后，OpenShift Serverless Logic 将无法访问这些文件。

如果您想添加到工作流的 OpenAPI 服务没有规范文件，您可以创建一个或更新服务以生成和公开该文件。

根据 OpenAPI 规范发送 REST 请求

要发送基于 OpenAPI 规范文件的 REST 请求，必须执行以下步骤

定义函数引用
访问工作流状态中定义的函数

先决条件

您已在集群上安装 OpenShift Serverless Logic 运算符。
您可以访问具有适当角色和权限的 OpenShift Serverless Logic 项目，以便在 OpenShift Container Platform 中创建应用程序和其他工作负载。
您可以访问 OpenAPI 规范文件。

步骤

要定义 OpenAPI 函数

标识并访问您打算调用的服务的 OpenAPI 规范文件。

将 OpenAPI 规范文件复制到您的工作流服务目录中，例如 `src/main/resources/specs`。

以下示例显示了乘法 REST 服务的 OpenAPI 规范

示例乘法 REST 服务 OpenAPI 规范

openapi: 3.0.3
info:
  title: Generated API
  version: "1.0"
paths:
  /:
    post:
      operationId: doOperation
      parameters:
        - in: header
          name: notUsed
          schema:
            type: string
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiplicationOperation'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    format: float
                    type: number
components:
  schemas:
    MultiplicationOperation:
      type: object
      properties:
        leftElement:
          format: float
          type: number
        rightElement:
          format: float
          type: number

要在工作流中定义函数，请使用 OpenAPI 规范中的 `operationId` 来引用函数定义中所需的运算。

温度转换应用程序中的示例函数定义

{
   "functions": [
     {
       "name": "multiplication",
       "operation": "specs/multiplication.yaml#doOperation"
     },
     {
       "name": "subtraction",
       "operation": "specs/subtraction.yaml#doOperation"
     }
   ]
}

确保您的函数定义引用存储在 `src/main/resources/specs` 目录中的 OpenAPI 文件的正确路径。

要在工作流状态中访问已定义的函数

定义工作流操作以调用您添加的函数定义。确保每个操作都引用前面定义的函数。

使用 `functionRef` 属性按名称引用特定函数。使用 OpenAPI 规范中定义的参数映射 `functionRef` 中的参数。

以下示例显示了如何在请求路径而不是请求正文中映射参数，您可以参考以下 PetStore API 示例

工作流中映射函数参数的示例

{
   "states": [
    {
      "name": "SetConstants",
      "type": "inject",
      "data": {
        "subtractValue": 32.0,
        "multiplyValue": 0.5556
      },
      "transition": "Computation"
    },
    {
      "name": "Computation",
      "actionMode": "sequential",
      "type": "operation",
      "actions": [
        {
          "name": "subtract",
          "functionRef": {
            "refName": "subtraction",
            "arguments": {
              "leftElement": ".fahrenheit",
              "rightElement": ".subtractValue"
            }
          }
        },
        {
          "name": "multiply",
          "functionRef": {
            "refName": "multiplication",
            "arguments": {
               "leftElement": ".difference",
               "rightElement": ".multiplyValue"
            }
          }
        }
      ],
      "end": {
        "terminate": true
      }
    }
  ]
}

查看 OpenAPI 规范的“操作对象”部分，了解如何构造请求中的参数。
使用 `jq` 表达式从有效负载中提取数据并将其映射到所需的参数。确保引擎根据 OpenAPI 规范映射参数名称。

对于在请求路径而不是正文中需要参数的操作，请参考 OpenAPI 规范中的参数定义。

有关在请求路径而不是请求正文中映射参数的更多信息，您可以参考以下 PetStore API 示例

映射路径参数的示例

{
  "/pet/{petId}": {
    "get": {
      "tags": ["pet"],
      "summary": "Find pet by ID",
      "description": "Returns a single pet",
      "operationId": "getPetById",
      "parameters": [
        {
          "name": "petId",
          "in": "path",
          "description": "ID of pet to return",
          "required": true,
          "schema": {
            "type": "integer",
            "format": "int64"
          }
        }
      ]
    }
  }
}

以下是函数调用的示例，其中仅在请求路径中添加了一个名为 `petId` 的参数

调用 PetStore 函数的示例

{
  "name": "CallPetStore", (1)
  "actionMode": "sequential",
  "type": "operation",
  "actions": [
    {
      "name": "getPet",
      "functionRef": {
        "refName": "getPetById", (2)
        "arguments": { (3)
          "petId": ".petId"
        }
      }
    }
  ]
}

1	状态定义，例如 `CallPetStore`。
2	函数定义引用。在前面的示例中，函数定义 `getPetById` 用于 PetStore OpenAPI 规范。
3	参数定义。OpenShift Serverless Logic 在发送请求之前将参数 `petId` 添加到请求路径。

配置 OpenAPI 服务的端点 URL

在工作流状态中访问函数定义后，您可以配置 OpenAPI 服务的端点 URL。

先决条件

您可以访问具有适当角色和权限的 OpenShift Serverless Logic 项目，以便在 OpenShift Container Platform 中创建应用程序和其他工作负载。
您已创建 OpenShift Serverless Logic 项目。
您可以访问 OpenAPI 规范文件。
您已在工作流中定义函数定义。
您可以访问工作流状态中定义的函数。

步骤

找到要配置的 OpenAPI 规范文件。例如，`substraction.yaml`。
将文件名转换为有效的配置键，方法是将特殊字符（例如 `.`）替换为下划线并将字母转换为小写。例如，将 `substraction.yaml` 更改为 `subtraction_yaml`。
要定义配置键，请使用转换后的文件名作为 REST 客户端配置键。将此键设置为环境变量，如下例所示
```
quarkus.rest-client.subtraction_yaml.url=http://myserver.com
```
为了避免在 `application.properties` 文件中硬编码 URL，请使用环境变量替换，如下例所示
```
quarkus.rest-client.subtraction_yaml.url=${SUBTRACTION_URL:http://myserver.com}
```
在此示例中
- 配置键：`quarkus.rest-client.subtraction_yaml.url`
- 环境变量：SUBTRACTION_URL
- 回退 URL：`http://myserver.com`
确保在您的系统或部署环境中设置了 `(SUBTRACTION_URL)` 环境变量。如果找不到该变量，应用程序将使用回退 URL `(http://myserver.com)`。

将配置键和 URL 替换添加到 `application.properties` 文件

quarkus.rest-client.subtraction_yaml.url=${SUBTRACTION_URL:http://myserver.com}

部署或重新启动应用程序以应用新的配置设置。