8.7. 部署 3scale ActiveDoc 自定义资源
Red Hat 3scale API Management ActiveDocs 基于 API 定义文档，用于定义符合 OpenAPI 规格的 RESTful Web 服务。ActiveDoc 自定义资源(CR)是导入 OpenAPI 规格(OAS)文档的一种方法，您可以在 Developer Portal 中用于 ActiveDocs。OAS 是一个标准，不会将您绑定到使用与 API 使用一个特定的编程语言。人工和计算机可以更轻松地了解 API 产品的功能，而无需源代码访问、文档或网络流量检查。
先决条件
- 具有 3scale 2.11 On-Premises 实例的管理员特权的用户帐户。
- 定义 API 的 OAS 文档。
-
了解
ActiveDocCR 如何链接到租户。
8.7.1. 部署 3scale ActiveDoc 自定义资源，从 secret 中导入 OAS 文档
部署 ActiveDoc 自定义资源 (CR)，以便您可以创建 3scale 后端和产品。
Operator 只读取 secret 中的内容。Operator 不读取 secret 中的字段名称。例如，数据以 key: value 对的形式构建，其中 value 代表文件的内容，key 是文件名。Operator 在 ActiveDoc CRD 的上下文中会忽略文件名。Operator 只读取文件的内容。
先决条件
- 了解 3scale 操作器如何标识自定义资源链接的租户。
定义包含 OAS (OpenAPI 规格) 文档的 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
定义您的
ActiveDocCR。确保指定包含 OAS 文档的 secret 的引用。例如，您可以创建myactivedoccr1.yaml文件：apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 spec: name: "Operated ActiveDoc From secret" activeDocOpenAPIRef: secretRef: name: myoasdoc1创建您刚刚定义的资源。例如：
$ oc create -f myactivedoccr1.yaml
对于给定示例，输出为：
activedoc.capabilities.3scale.net/myactivedoccr1 created
验证
- 登录到您的 Red Hat OpenShift Container Platform (OCP) 管理员帐户。
- 进入 Operators > Installed Operators。
- 点 Red Hat Integration - 3scale。
- 点 Active Doc 选项卡。
-
确认存在 OAS 文档。对于上例，您会看到一个名为
myactivedoccr1的新 OAS 文档。
8.7.2. 3scale ActiveDoc 自定义资源定义的功能
ActiveDoc 自定义资源定义 (CRD) 与开发人员 OpenAPI 文档格式的产品文档相关。了解 ActiveDoc CRD 部署功能可帮助您为开发人员门户创建 ActiveDocs。
ActiveDocCR，可从以下任一位置读取 OpenAPI 文档：- Secret
-
http或https格式的 URL
-
另外，您可以使用
productSystemName字段将ActiveDocCR 与 3scale 产品相关联。该值必须是 3scale 产品的 CR 的system_name。 -
您可以使用
published字段发布或隐藏 3scale 中的ActiveDoc文档。默认情况下，这设置会被隐藏。 -
您可以使用
skipSwaggerValidations字段来跳过 OpenAPI 3.0 验证。默认情况下，ActiveDocCR 会被验证。
8.7.3. 部署 3scale ActiveDoc 自定义资源，从 URL 中导入 OAS 文档
您可以部署一个 ActiveDoc 自定义资源 (CR)，从您指定的 URL 中导入 OAS (OpenAPI 规格) 文档。然后，您可以在 Developer Portal 中使用此 OAS 文档作为您的 API 的 ActiveDocs 的基础。
先决条件
流程
- 在 OpenShift 帐户中，进入到 Operators > Installed operators。
- 点 3scale operator。
- 点 Active Doc 选项卡。
创建
ActiveDocCR。例如：apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 spec: openapiRef: url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml" providerAccountRef: name: mytenant可选。对于自我管理的 APIcast，在
ActiveDocCR 中，将productionPublicBaseURL和stagingPublicBaseURL字段设置为部署的 URL。例如：apiVersion: capabilities.3scale.net/v1beta1 kind: ActiveDoc metadata: name: myactivedoccr1 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"-
点击 Save。3scale operator 需要几秒钟时间来创建
ActiveDocCR。
验证
- 登录到您的 Red Hat OpenShift Container Platform (OCP) 管理员帐户。
- 进入 Operators > Installed Operators。
- 点 Red Hat Integration 3scale。
- 点 Active Doc 选项卡。
-
确认存在 OAS 文档。对于上例，您会看到一个名为
myactivedoccr1的新 OAS 文档。
