8.6. 部署 3scale OpenAPI 自定义资源

OpenAPI 自定义资源(CR)是导入 OpenAPI 规格(OAS)文档的一种方法，您可以在 Developer Portal 中用于 ActiveDocs。OAS 是一个标准，不会将您绑定到使用与 API 使用一个特定的编程语言。人工和计算机可以更轻松地了解 API 产品的功能，而无需源代码访问、文档或网络流量检查。

先决条件

具有 3scale 2.11 On-Premises 实例的管理员特权的用户帐户。
定义 API 的 OAS 文档。
了解 OpenAPI CR 如何与租户链接。

8.6.1. 部署 3scale OpenAPI 自定义资源，从 secret 中导入 OAS 文档

部署 OpenAPI 自定义资源 (CR)，以便您可以创建 3scale 后端和产品。

注意

Operator 只读取 secret 中的内容。Operator 不读取 secret 中的字段名称。

先决条件

了解 3scale 操作器如何标识自定义资源链接的租户。

流程

定义包含 OAS 文档的 secret。例如，您可以使用以下内容创建 myoasdoc1.yaml ：

openapi: "3.0.2"
info:
  title: "some title"
  description: "some description"
  version: "1.0.0"
paths:
  /pet:
    get:
      operationId: "getPet"
      responses:
        405:
          description: "invalid input"

创建 secret.例如：

$ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml

secret/myoasdoc1 created

定义 OpenAPI CR。确保指定包含 OAS 文档的 secret 的引用。例如，您可以创建 myopenapicr1.yaml 文件：

apiVersion: capabilities.3scale.net/v1beta1
kind: OpenAPI
metadata:
  name: myopenapicr1
spec:
  openapiRef:
    secretRef:
      name: myoasdoc1

创建您刚刚定义的资源。例如：

$ oc create -f myopenapicr1.yaml

对于给定示例，输出为：

openapi.capabilities.3scale.net/myopenapicr1 created

8.6.2. 3scale OpenAPI 自定义资源定义的功能

了解 OpenAPI 自定义资源定义(CRD)部署功能将有助于您配置 3scale 产品、后端并为开发者门户创建 ActiveDocs。

OAS 文档可以从以下项读取：
- Kubernetes secret
- http 和 https 格式的 URL
在 OAS 文档中，info.title 设置不能超过 215 个字符。Operator 使用此设置来创建 OpenShift 对象名称，其长度限制。
只有服务器列表中的第一个 server[0].url 元素将解析为私有 URL。OpenAPI 规格(OAS)使用其 server[0].url 元素的 basePath 组件。
OpenAPI CRD 支持单个顶层安全要求，但它不支持操作级别的安全性。
OpenAPI CRD 支持 apiKey 安全方案。

其他资源

8.6.3. 定义 OpenAPI 自定义资源时导入规则

导入规则指定当为 3scale 部署设置 OpenAPI 文档时，OpenAPI 规格(OAS)如何与 3scale 一起工作。

产品名称

默认产品系统名称通过 OpenAPI 文档中的 info.title 字段获取。要覆盖 OpenAPI 文档中的产品名称，在 OpenAPI 自定义资源(CR)中指定 spec.productSystemName 字段。

私有基本 URL

私有基础 URL 从 OpenAPI CR servers[0].url 字段读取。您可以使用 OpenAPI CR 中的 spec.privateBaseURL 字段来覆盖它。

3scale 方法

导入 OpenAPI 文档中定义的每个操作都会转换为产品级别的一个 3scale 方法。方法名称从操作对象的 operationId 字段读取。

3scale 映射规则

导入 OpenAPI 文档中定义的每个操作都会转换为产品级别的 3scale 映射规则。以前，现有映射规则由使用 OpenAPI CR 导入的用户替代。

在 OpenAPI 文档中，paths 对象提供了用于操作动词和模式属性的映射规则。3scale 方法相应地与 operationId 关联。

delta 值硬编码为 1。

默认情况下配置严格匹配策略。可以使用 OpenAPI CRD 的 spec.PrefixMatching 字段切换到前缀匹配。

身份验证

只支持一个顶级安全要求。不支持操作级别的安全要求。

支持的安全方案是 apiKey。

apiKey 安全方案类型：

凭证位置 将从安全方案对象的 in 字段中的 OpenAPI 文档读取。
Auth user 键将从安全方案对象的 OpenAPI 文档的 name 字段中读取。

以下是 OAS 3.0.2 部分带有 apiKey 安全要求的部分示例：

openapi: "3.0.2"
security:
  - petstore_api_key: []
components:
  securitySchemes:
    petstore_api_key:
      type: apiKey
      name: api_key
      in: header

当 OpenAPI 文档没有指定任何安全要求时，会应用以下内容：

产品身份验证将为 apiKey 配置。
凭证位置 将默认为 3scale 值 As query parameters (GET) or body parameters (POST/PUT/DELETE)。
Auth user 密钥默认为 3scale 值 user_key。

3scale Authentication Security 可以使用 OpenAPI CRD 的 spec.privateAPIHostHeader 和 spec.privateAPISecretToken 字段来设置。

ActiveDocs

不会创建 3scale ActiveDoc。

3scale 产品策略链

3scale 策略链是默认 3scale 创建的。

3scale 部署模式

默认情况下，配置的 3scale 部署模式将为 APIcast 3scale 管理。但是，当 spec.productionPublicBaseURL 或 spec.stagingPublicBaseURL 或两个字段都位于 OpenAPI CR 中时，产品的部署模式是 APIcast 自我管理的。

带有自定义公共基础 URL 的 OpenAPI CR 示例：

apiVersion: capabilities.3scale.net/v1beta1
kind: OpenAPI
metadata:
  name: openapi1
spec:
  openapiRef:
    url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
  productionPublicBaseURL: "https://production.my-gateway.example.com"
  stagingPublicBaseURL: "https://staging.my-gateway.example.com"

8.6.4. 部署 3scale OpenAPI 自定义资源，从 URL 导入 OAS 文档

您可以部署从您指定的 URL 中导入 OAS 文档的 OpenAPI 自定义资源。然后，您可以在 Developer Portal 中使用此 OAS 文档作为您的 API 的 ActiveDocs 的基础。

先决条件

如果您要创建一个 OpenAPI 自定义资源，它没有链接到同一命名空间中的 3scale 实例中默认租户，则该命名空间将包含 OpenAPI CR 的 secret 包含一个用于标识 OpenAPI CR 链接的租户。secret 的名称是以下之一：
- threescale-provider-account
- 用户定义
此机密包含 3scale 实例的 URL 和令牌，其中包含用于访问 3scale 实例中某一租户的凭据。

流程

在 OpenShift 帐户中，进入到 Operators > Installed operators。
点 3scale operator。
选择 YAML 选项卡。

创建 OpenAPI 自定义资源。例如：

apiVersion: capabilities.3scale.net/v1beta1
kind: OpenAPI
metadata:
  name: openapi1
spec:
  openapiRef:
    url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
  providerAccountRef:
    name: mytenant

点击 Save。3scale 操作器需要几秒钟时间来创建 OpenAPI CR。

验证

在 OpenShift 中，在 3scale Product Overview 页面中，确认 Synced 条件被标记为 True。
进入 3scale 帐户。
确认存在 OAS 文档。对于上例，您会看到一个名为 openapi1 的新 OAS 文档。

8.6. 部署 3scale OpenAPI 自定义资源

8.6.1. 部署 3scale OpenAPI 自定义资源，从 secret 中导入 OAS 文档

8.6.2. 3scale OpenAPI 自定义资源定义的功能

8.6.3. 定义 OpenAPI 自定义资源时导入规则

8.6.4. 部署 3scale OpenAPI 自定义资源，从 URL 导入 OAS 文档

8.6.5. 其他资源

学习

尝试、购买和销售

社区

关于红帽文档

让开源更具包容性

關於紅帽

Red Hat legal and privacy links

Red Hat legal and privacy links