Анализ API в центре API — управление Майкрософт

Центр API вашей организации включает встроенные функции линтинга, управляемые Майкрософт (предварительная версия), для анализа определений API на соответствие правилам стиля организации, что позволяет создавать как отдельные, так и сводные отчёты. Анализ API определяет и помогает исправить распространенные ошибки и несоответствия в определениях API.

С помощью анализа API:

• Центр API Azure автоматически анализирует определения API при добавлении или обновлении определения API. Линтинг определений API выполняется по умолчанию с использованием spectral:oas набора правил (руководство по стилю API).
• Отчеты анализа API создаются в портале Azure, которые показывают, как определения API соответствуют руководству по стилю.
• Используйте профили анализа, чтобы указать набор правил и условия фильтрации для анализируемых API. Настройте набор правил профиля с помощью расширения Центра API Azure для Visual Studio Code.

Внимание

Если вы предпочитаете, вы можете включить самостоятельно управляемый линтинг и анализ с помощью пользовательской функции Azure, чтобы переопределить встроенные возможности. Отключите любую функцию, используемую для самоуправляемого линтинга, перед использованием анализа, проводимого с помощью управляемого API.

Ограничения

• В настоящее время анализируются только документы спецификации OpenAPI и AsyncAPI в формате JSON или YAML.
• Существуют ограничения на количество профилей анализа и максимальное количество проанализированных определений API. Для завершения анализа может потребоваться несколько минут до 24 часов.

Предварительные условия

• Центр API в подписке Azure. Если у вас еще нет, см. краткое руководство. Создание центра API.
• Для настройки набора правил в Visual Studio Code и следующих расширений Visual Studio Code:
  • Расширение Центра API Azure для Visual Studio Code
  • Расширение Spectral для Visual Studio Code

Просмотр отчетов по анализу API

Просмотрите сводку по анализу и отчеты по анализу определений API в портале Azure. После анализа определений API выводится список ошибок, предупреждений и сведений в соответствии с настроенным руководством по стилю API.

В отчете по анализу API также просмотрите набор правил, использованный для анализа, и историю проверок с помощью линтеров.

Чтобы просмотреть сводку по анализу в центре API, выполните следующие действия.

1. На портале перейдите в центр API.

2. В меню слева в разделе "Управление" выберите "Анализ API". Появляется резюме.

   

3. При необходимости выберите значок отчета анализа API для определения API. Появится отчет по анализу API определения, как показано на следующем снимке экрана.

   

   Совет

   Вы также можете просмотреть отчет по анализу API, выбрав "Анализ " в строке меню определения API.

Управление профилями анализа

Центр API Azure использует профили анализа для линтинга и анализа API. Профиль анализа определяет набор правил и при необходимости фильтрует условия для анализируемых API. Профиль анализа по умолчанию применяет spectral:oas набор правил ко всем определениям OpenAPI и AsyncAPI.

Вы можете настроить набор правил и определить условия фильтра в профиле по умолчанию или создать новый профиль. Например, может потребоваться использовать один профиль для API, которые находятся в разработке, и другой для API, которые находятся в рабочей среде.

Замечание

В стандартном плане Центра API можно создать до трех профилей анализа. В плане "Бесплатный" поддерживается только один профиль.

Чтобы создать профиль анализа, выполните приведенные действия.

1. На портале Azure перейдите в центр API.
2. В меню слева в разделе "Генеральное управление" выберите "Анализ API">, "Управление профилями анализа> и "Создать профиль анализа".
3. В области создания профиля анализа введите имя и описание профиля.
4. В наборе правил отображается тип анализатора (подсистема подкладок) для набора правил. В настоящее время поддерживается только Spectral.
5. В разделе "Определение условий фильтра" добавьте одно или несколько условий фильтра для определений API, к которым применяется профиль.
6. Нажмите кнопку "Создать".

Создается профиль и создается шаблон набора правил. Чтобы просмотреть текущий набор правил, выберите профиль и в контекстном меню (...) выберите "Просмотреть набор правил".

Чтобы настроить набор правил, перейдите к следующим разделам.

Настройка набора правил профиля

Используйте расширение Visual Studio Code для центра API Azure для настройки набора правил профиля. После настройки набора правил и локального тестирования его можно развернуть обратно в центре API.

1. В Visual Studio Code щелкните значок Центра API Azure на панели действий.
2. В области Центра API разверните ресурс центра API, с которым вы работаете, и разверните профили.
3. Разверните профиль, который вы хотите изменить, и выберите ruleset.yaml.
4. При необходимости измените или замените содержимое.
5. Сохраните изменения в файле ruleset.yaml.

Тестировать набор правил локально

Перед развертыванием настраиваемого набора правил в центре API проверьте его локально. Расширение Центра API Azure для Visual Studio Code обеспечивает встроенную поддержку линтинга спецификаций API с помощью Spectral.

1. В Visual Studio Code используйте сочетание клавиш CTRL+SHIFT+P , чтобы открыть палитру команд.

2. Введите Azure API Center: установите активное руководство по стилю API и нажмите клавишу ВВОД.

3. Выберите "Выбрать локальный файл " и укажите настроенный ruleset.yaml файл. Нажмите клавишу ВВОД.

   Этот шаг делает настраиваемый набор правил активным стилевым руководством API для локального линтинга.

Теперь, когда вы открываете файл определения API в формате OpenAPI, в Visual Studio Code автоматически запускается локальный линтинг. Результаты встроены в редакторе и отображаются в окне "Проблемы" (Просмотр > Проблем или CTRL+SHIFT+M).

Совет

Разработчики API в вашей организации также могут использовать локальную возможность анализа кода, чтобы улучшить определения API перед их регистрацией в центре управления API.

Просмотрите результаты линтинга. Внесите необходимые изменения в набор правил и продолжайте тестировать его локально, пока он не будет работать так, как вам нужно.

Развертывание набора правил в центре API

Чтобы развернуть настраиваемый набор правил в центре API, выполните следующие действия.

1. В Visual Studio Code щелкните значок Центра API Azure на панели действий.
2. В области «Центр API» разверните ресурс, в котором вы настроили набор правил.
3. Разверните Профили.
4. Щелкните правой кнопкой мыши профиль, в котором вы настроили набор правил, и выберите пункт "Развернуть правила" в Центре API.

Сообщение уведомляет вас после успешного развертывания правил в центре API. Движок линтинга использует обновленный набор правил для анализа определений API в профиле.

Чтобы увидеть результаты линтинга с обновленными правилами, ознакомьтесь с отчетами анализа API на портале.

Связанный контент

• Дополнительные сведения о встроенном наборе правил по умолчанию см. в репозитории Spectral GitHub.
• Включение анализа API в центре API — самостоятельное управление