通过

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

分析 API 中心中的 API - Microsoft 托管

  • 项目

组织的 API 中心包括内置的 Microsoft 托管 Lint 分析功能（预览版），用于分析 API 定义是否符合组织样式规则，同时生成单个报告和摘要报告。 API 分析可以识别和帮助你更正 API 定义中的常见错误和不一致。

使用 API 分析的益处：

  • 每当添加或更新 API 定义时，Azure API 中心都会自动分析 API 定义。 默认情况下，API 定义使用 spectrum:oas 规则集（API 样式指南）进行 lint 分析。
  • API 分析报告是在 Azure 门户中生成的，其中显示了 API 定义与样式指南的符合程度。
  • 可以使用适用于 Visual Studio Code 的 Azure API 中心扩展在本地自定义和测试自己的 API 样式指南，然后将其部署到 API 中心。

重要

如果愿意，可以使用自定义 Azure 函数启用自托管的 Lint 分析和分析，从而替代内置功能。 使用托管 API 分析之前，禁用用于自托管 Lint 分析的任何函数。

限制

  • 目前，仅会分析 JSON 或 YAML 格式的 OpenAPI 和 AsyncAPI 规范文档。
  • 目前，请配置单个规则集，并将其应用于 API 中心中的所有 OpenAPI 定义。
  • 分析的 API 定义数具有最大数量限制。 分析可能需要几分钟到长达 24 小时才能完成。

先决条件

查看 API 分析报告

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

在 API 分析报告中，还可查看用于分析的规则集和 Lint 分析传递历史记录。

在 API 中心查看分析摘要：

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

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

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

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

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

    提示

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

自定义规则集

可以使用适用于 Visual Studio Code 的 Azure API 中心扩展来自定义 API 中心的默认规则集，或将其替换为组织的 API 样式指南。 例如，可以扩展规则集或添加自定义函数。

自定义或替换规则集：

  1. 在 Visual Studio Code 中，选择“活动栏”中的 Azure API 中心图标。
  2. 打开工作文件夹根目录下的 .api-center-rules 文件夹。
  3. 在 API 中心资源的文件夹中，打开 ruleset.yml 文件。
  4. 根据需要修改或替换内容。
  5. 保存对 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）。

提示

组织中的 API 开发人员还可以使用此本地 Lint 分析功能来帮助改进 API 定义，然后再在 API 中心注册 API。

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

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

将规则集部署到 API 中心

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

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

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

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

相关内容