使用 Governance 服务验证 API 或产品文档

如何使用 监管 规则集来验证和实施组织监管策略和最佳实践。 您可以从 API Manager UI ， API Designer UI 或 工具箱 CLI对 API 和产品文档运行验证扫描。

准备工作

必须先由系统管理员在管理子系统上启用 监管 ，然后才能运行验证扫描。 请参阅 在 Kubernetes 上启用 治理和 在 VMware 上启用 治理 以获取更多信息。 如果在部署中启用了 监管 ，那么会在侧边菜单栏中显示 监管 图标 治理图标是黑色背景上的白盾的轮廓。 。 如果您只是提供者组织的目录或空间成员，那么 监管 选项卡将显示在目录菜单中。

Governance 服务可供所有用户角色使用。

治理服务有以下限制：
  • 它不支持去引用，这意味着它不会自动反省 API 中的引用定义。 不过，您可以根据需要使用自定义规则显式验证引用对象，以确保符合您的 API 标准。
  • 治理服务中未启用以下 OpenAPI Specification (OAS) 规则，以防止出现误报错误：
提示： 在使用治理服务验证任何 API 文档之前，应首先运行 Validate > With specifications 来验证 OpenAPI YAML 源。 更多信息，请参阅验证 OpenAPI YAML 源。

关于此任务

IBM® API Connect 中的 监管 服务可用于对 API 和产品开发过程验证和实施组织监管策略和最佳实践。 该服务包含以下类型的规则集:
API
用于验证 API 文档的规则集。
  • 提供者组织规则集 -这些是定制规则集，其中包含在您的提供者组织中创建的规则，并且特定于您的提供者组织，用于验证 API。
  • 全局规则集 -这些规则集是预先配置的 IBM 和 谱 规则集，其中包含与提供者组织共享的用于验证 API 的规则，无法进行编辑。 请注意， 谱 规则集名称以 spectral-为前缀，并且其版本与 谱中提供的该规则集的版本相匹配。
产品
用于验证产品文档的规则集。 请注意，产品的验证扫描仅查看产品 yaml; 它不包括扫描产品所引用的任何 API 文档。
  • 提供者组织规则集 -这些是定制规则集，其中包含在提供者组织中创建的规则以及特定于提供者组织的规则，用于验证产品。
  • 全局规则集 -这些是预先配置的定制规则集，其中包含与提供者组织共享的用于验证产品的规则，无法进行编辑。

您可以创建自己的提供商组织规则集来验证您的 Swagger、OpenAPI, AsyncAPI,和产品文档，也可以使用为您的组织提供的全局规则集。 有关配置规则集的更多信息，请参阅 在 API 管理器 中配置 治理。

API Connect 中的治理功能基于开源的 Spectral 插件；有关 Spectral 的更多信息，请参见 https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview.

您可以通过使用 API Manager UI 或使用 API Designer (当 UI 处于联机状态时)来完成此任务中的指示信息，并连接到在其中启用了 监管 微服务的云实例。 您也可以使用工具包 CLI；详情请参阅使用工具包 CLI 验证 API 或产品文档。

提供了以下验证扫描方法:

过程

  • 要从 API 中验证 API 文档，请完成以下步骤。
    1. 打开所需的 API 以进行验证，如 编辑 OpenAPI 2.0 API 定义 或 编辑 OpenAPI 3.0 API 定义中所述。
    2. 单击标题菜单栏中的验证 > 使用规则集。
      显示 "验证" 按钮和 "保存" 按钮的标题菜单栏的截屏。
    3. 选择要验证 API 文档的规则集，然后单击 下一步。
      如果应用程序接口和规则集中有匹配的标记，验证过程就会预先选择扫描要使用的规则集。 不过，您可以用自己选择的规则集覆盖这一预选。 有关如何添加标记的信息，请参阅在API 管理器中配置治理，以及向 API 添加标记。
    4. 从要用于验证的规则集中选择规则。 缺省情况下，将选择所有规则。
    5. 单击 验证。
      如果发现任何验证错误，那么将显示显示验证结果的记分卡。 然后，可以更新 API 以解决验证错误，然后再次进行验证。 如果找不到错误，那么将显示成功消息。
    6. 可选: 您可以单击 下载 以将验证结果下载到 .csv 文件中。
    7. 可选: 您可以单击 上一步 以更改规则集和规则，然后再次运行验证。
    8. 完成时单击 完成 。
      这将显示 "API 设计 " 页面。
      如果在扫描期间发现验证错误，那么标题菜单栏中的规则集状态图标将显示找到的错误数，例如:
      标题菜单栏的截屏，其中显示了白色背景上盾牌黑色轮廓的规则集状态图标，验证扫描中发现的错误数显示为盾牌旁边红色圆圈内的白色数字 38。
      您可以单击规则集状态图标以查看错误及其在 YAML 中的位置的详细列表。 然后，您还可以单击单个错误以直接浏览到 API 中的相关部分。
  • 要从产品中验证产品文档，请完成以下步骤。
    1. 通过单击 " 开发 " 页面的 产品 选项卡中的产品标题，打开用于验证的必需产品。
    2. 从标题中的菜单栏单击 使用规则集进行验证 。
      显示 "验证" 按钮和 "保存" 按钮的标题菜单栏的截屏。
    3. 选择要针对其验证产品文档的规则集，然后单击 下一步。
    4. 从要用于验证的规则集中选择规则。 缺省情况下，将选择所有规则。
    5. 单击 验证。
      如果发现任何验证错误，那么将显示显示验证结果的记分卡。 然后，可以更新产品以解决验证错误，然后再次进行验证。 如果找不到错误，那么将显示成功消息。
    6. 可选: 您可以单击 下载 以将验证结果下载到 .csv 文件中。
    7. 可选: 您可以单击 上一步 以更改规则集和规则，然后再次运行验证。
    8. 完成时单击 完成 。
      这将显示产品 " 设计 " 页面。
  • 要从 监管 部分中验证一个或多个草稿 API 或产品文档，请完成以下步骤。
    1. 在侧菜单栏中，单击 治理图标是黑色背景上的白盾的轮廓。 Governance。
      这将显示 " 监管 " 页面。
    2. 单击 规则集 选项卡。
    3. 如果要验证一个或多个 API 文档，请单击 API 选项卡。 如果要验证一个或多个产品文档，请单击 产品 选项卡。
    4. 单击 验证。
    5. 选择要验证的规则集，然后单击 下一步。
      如果应用程序接口和规则集中有匹配的标记，验证过程就会预先选择扫描要使用的规则集。 不过，您可以用自己选择的规则集覆盖这一预选。 有关如何添加标记的信息，请参阅在API 管理器中配置治理，以及向 API 添加标记。
    6. 从要用于验证的规则集中选择规则，然后单击 下一步。
    7. 选择要验证的 API 或产品，然后单击验证。
      如果发现任何验证错误，那么将显示显示验证结果的记分卡。 如果找不到错误，那么将显示成功消息。
    8. 可选: 您可以单击 下载 以将验证结果下载到 .csv 文件中。
    9. 可选: 您可以单击 上一步 以更改规则集，规则和 API ，然后再次运行验证。
    10. 完成时单击 完成 。
  • 要从目录或空间中验证一个或多个已发布的 API 或产品文档，请完成以下步骤。
    1. 选择要在其中运行验证的目录或空间，然后从菜单栏中选择 监管 。
    2. 选择 规则集。
    3. 如果要验证一个或多个 API 文档，请单击 API 选项卡。 如果要验证一个或多个产品文档，请单击 产品 选项卡。
    4. 单击 验证。
    5. 选择要验证的规则集，然后单击 下一步。
      如果应用程序接口和规则集中有匹配的标记，验证过程就会预先选择扫描要使用的规则集。 不过，您可以用自己选择的规则集覆盖这一预选。 有关如何添加标记的信息，请参阅在API 管理器中配置治理，以及向 API 添加标记。
    6. 从要用于验证的规则集中选择规则，然后单击 下一步。
    7. 选择要验证的 API 或产品，然后单击验证。
      如果发现任何验证错误，那么将显示显示验证结果的记分卡。 如果找不到错误，那么将显示成功消息。
    8. 可选: 您可以单击 下载 以将验证结果下载到 .csv 文件中。
    9. 可选: 您可以单击 上一步 以更改规则集，规则和 API ，然后再次运行验证。
    10. 完成时单击 完成 。

结果

将针对一个或多个规则集验证 API 或产品文档。

后续操作

您可以使用验证结果来帮助您改进 API 或产品文档。 您还可以使用结果来帮助您编辑规则集，并创建新的规则集; 请参阅 在 API 管理器 中配置 治理 以获取更多信息。

您还可以对目录或空间运行验证扫描，以检查其中包含的一个或多个 API 文档。 有关更多信息，请参阅 扫描目录和空间。