通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在 API 中心启用 API 分析 - Microsoft 托管

  • 项目

本文介绍如何在 Azure API 中心中启用 API 分析，而无需自行管理 API（预览版）。 API 分析提供 linting 功能，用于在组织的 API 中心中分析 API 定义。 Linting 确保 API 可k义遵守组织的样式规则，从而同时生成单个报表和摘要报表。 使用 API 分析识别和更正 API 定义中的常见错误和不一致。

重要

API 中心中的托管 API 分析会自动设置 Lint 分析引擎和必要的依赖项。 你还可以使用自定义 Azure 函数手动启用 Lint 分析和一般分析。 启用托管 API 分析之前，禁用用于手动 Lint 分析的任何函数。

在本方案中：

  1. 使用适用于 Azure API 中心的 Visual Studio Code 扩展在 API 中心中添加 linting 规则集（API 样式指南）。
  2. 添加或更新 API 定义时，Azure API 中心会自动运行 linting。 将规则集部署到 API 中心时，也会针对所有 API 定义触发该规则集。
  3. 在 Azure 门户中查看 API 分析报告，了解 API 定义如何符合样式指南。
  4. （可选）为组织的 API 自定义规则集。 在本地测试自定义规则集，然后将其部署到 API 中心。

限制

  • 目前，仅会分析 JSON 或 YAML 格式的 OpenAPI 规范文档。
  • 默认情况下，使用 spectral:oas 规则集启用分析。 若要详细了解内置规则，请参阅 Spectral GitHub 存储库。
  • 目前，请配置单个规则集，并将其应用于 API 中心中的所有 OpenAPI 定义。
  • 分析的 API 定义数具有最大数量限制。 分析可能需要几分钟到长达 24 小时才能完成。

先决条件

使用 Visual Studio Code 启用 API 分析

若要使用默认 linting 规则集启用 API 分析，请执行以下操作：

  1. 在 Visual Studio Code 中，打开一个文件夹，用于管理 Azure API 中心的规则集。

  2. 从活动栏中选择 Azure API 中心图标。

  3. 在 API 中心窗格中，展开要在其中启用 API 分析的 API 中心资源。

  4. 右键单击“规则”并选择“启用 API 分析”。

    在 Visual Studio Code 中启用 API linting 和分析的屏幕截图。

成功启用 API 分析后，消息会通知你。 API 中心的文件夹会在工作文件夹的根目录中创建 .api-center-rules。 API 中心的文件夹包含：

  • 定义 linting 引擎使用的默认 API 样式指南的 ruleset.yml 文件。
  • functions 文件夹，其中包含可用于扩展规则集的示例自定义函数。

启用分析后，linting 引擎会基于默认规则集分析 API 中心中的 API 定义，并生成 API 分析报告。

查看 API 分析报告

在 Azure 门户中查看 API 定义的分析摘要和分析报告。 分析 API 定义后，报告会根根据配置的 API 样式指南列出错误、警告和信息。

在 API 中心查看分析摘要：

  1. 在门户中，导航到你的 API 中心。

  2. 在左侧菜单的“治理”下，选择“API 分析”。 此时会显示摘要。

    门户中 API 分析摘要的屏幕截图。

  3. （可选）为 API 定义选择 API 分析报告图标。 将显示定义的 API 分析报告，如以下屏幕截图所示。

    门户中 API 分析报告的屏幕截图。

    提示

    还可以通过从 API 定义的菜单栏中选择“分析”来查看 API 分析报告。

自定义规则集

可以自定义默认规则集，或将其替换为组织的 API 样式指南。 例如，可以扩展规则集或添加自定义函数。

自定义或替换规则集：

  1. 在 Visual Studio Code 中，打开 .api-center-rules 工作文件夹根目录下的文件夹。
  2. 在 API 中心资源的文件夹中，打开 ruleset.yml 文件。
  3. 根据需要修改或替换内容。
  4. 保存对 ruleset.yml 的更改。

在本地测试规则集

将自定义规则集部署到 API 中心之前，请在本地验证它。 适用于 Visual Studio Code 的 Azure API 中心扩展为使用 Spectral 处理 API 规范提供集成支持。

  1. 在 Visual Studio Code 中，使用键盘快捷方式 (Ctrl+Shift+P) 开启命令面板。

  2. 输入“Azure API 中心：设置活动 API 样式指南”，然后按“Enter”。

  3. 选择“选择本地文件”并指定自定义的 ruleset.yml 文件。 按“Enter”。

    此步骤使自定义规则集成为用于 linting 的活动 API 样式指南。

现在，打开基于 OpenAPI 的 API 定义文件时，Visual Studio Code 中会自动触发本地 linting 操作。 系统会在编辑器和“问题”窗口中以内联方式显示结果，（视图>问题或 Ctrl+Shift+M）。

在 Visual Studio Code 中对API定义进行 linting 的屏幕截图。

查看 linting 结果。 对规则集进行任何必要的调整，并继续在本地测试，直到它按所需方式执行。

将规则集部署到 API 中心

将自定义规则集部署到 API 中心：

  1. 在 Visual Studio Code 中，选择“活动栏”中的 Azure API 中心图标。
  2. 在 API 中心窗格中，展开自定义规则集的 API 中心资源。
  3. 右键单击“规则”并选择“将规则部署到 API 中心”。

成功将规则部署到 API 中心后，消息会通知你。 linting 引擎使用更新的规则集来分析 API 定义。

若要查看使用更新的规则集进行 linting 的结果，请查看门户中的 API 分析报告。

相关内容