Импорт спецификации OpenAPI

Статья
2025-04-08

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни API-менеджмента

В этой статье показано, как импортировать спецификацию OpenAPI в Управление API Azure с помощью различных средств. Также здесь показано, как протестировать программный интерфейс в службе "Управление API".

В этой статье вы узнаете, как:

Импорт спецификации OpenAPI с помощью портал Azure, Azure CLI или Azure PowerShell
проверка API на портале Azure;

Примечание.

Ограничения импорта API описаны в ограничениях импорта API и известных проблемах.

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

Экземпляр управления API. Если у вас его еще нет, выполните следующее краткое руководство по началу работы: Создайте экземпляр API Management в Azure.
Azure CLI
- Используйте среду Bash в Azure Cloud Shell. Для получения дополнительной информации см. краткое руководство по Bash в Azure Cloud Shell.
- Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.
  - Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.
  - Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.
  - Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.
Azure PowerShell
- Если вы решили использовать Azure PowerShell локально:
  - Установите последнюю версию модуля Az PowerShell.
  - Подключитесь к учетной записи Azure с помощью командлета Connect-AzAccount.
- Если вы решили использовать Azure Cloud Shell:
  - Дополнительные сведения см. в статье Общие сведения об Azure Cloud Shell.

Импорт внутреннего API

В этом примере вы импортируете спецификацию OpenAPI для open source API Petstore, но вы можете заменить спецификацию OpenAPI на другую по своему усмотрению.

В портале Azure перейдите к вашему экземпляру API Management.
В меню слева выберите API>+ Добавить API.
В разделе Создание из определения выберите OpenAPI.
Введите параметры API. Вы можете задать значения во время создания или настроить их позже, перейдя на вкладку "Параметры ". Параметры описаны в руководстве по импорту и публикации первого руководства по API .
Нажмите кнопку создания.

В следующем примере используется команда az apim api import для импорта спецификации OpenAPI из указанного URL-адреса в экземпляр API Management с именем apim-hello-world. Чтобы импортировать путь к спецификации вместо URL-адреса, используйте --specification-path параметр.

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

После импорта API при необходимости можно обновить параметры с помощью команды az apim api update .

В следующем примере используется командлет Import-AzApiManagementApi Azure PowerShell для импорта спецификации OpenAPI из указанного URL-адреса в экземпляр Управление API с именем apim-hello-world. Чтобы импортировать путь к спецификации вместо URL-адреса, используйте -SpecificationPath параметр.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

После импорта API при необходимости можно обновить параметры с помощью командлета Set-AzApiManagementApi .

Просмотр и изменение спецификации OpenAPI

На портале используйте редактор спецификаций OpenAPI для просмотра, проверки или изменения спецификации для импортированного API.

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

Перейдите к экземпляру Управления API на портале Azure.
В меню слева в разделе API выберите >>All operations.
На вкладке "Конструктор " в интерфейсе выберите редактор спецификаций OpenAPI (значок карандаша). Спецификацию можно открыть в формате JSON или YAML.
Просмотрите или измените спецификацию по мере необходимости. Сохраните свои изменения.

Проверка схемы спецификации OpenAPI

Вы можете настроить политику проверки в Управлении API для проверки запросов и ответов (или их элементов) на соответствие схеме в спецификации OpenAPI. Например, используйте политику проверки содержимого для проверки размера или содержимого текста запроса или ответа.

Проверка нового API на портале

Операции можно вызывать непосредственно на портале, что позволяет администраторам просматривать и тестировать операции API.

Выберите API, созданный на предыдущем шаге.
Откройте вкладку Тест.
Выберите операцию. На странице отобразятся поля для параметров запроса и для заголовков.

Примечание.

В тестовой консоли Управление API автоматически заполняет заголовок Ocp-Apim-Subscription-Key и настраивает ключ подписки встроенной подписки. Этот ключ обеспечивает доступ ко всем API в экземпляре управления API. При необходимости отобразите заголовок Ocp-Apim-Subscription-Key, выбрав значок "глаз" рядом с HTTP-запросом.
В зависимости от операции введите значения параметров запроса, значения заголовков или текст запроса. Выберите Отправить.

При успешном выполнении теста серверная часть отвечает успешным кодом ответа HTTP и некоторыми данными.

Совет

По умолчанию тестовая консоль отправляет запрос на прокси-сервер CORS управления API, который перенаправляет запрос в экземпляр управления API, после чего он передается в бекенд. Этот прокси-сервер использует общедоступный IP-адрес 13.91.254.72 и может получать доступ только к общедоступным конечным точкам. Если вы хотите отправить запрос непосредственно из браузера в службу Управление API, выберите "Обход прокси CORS". Используйте этот параметр, если вы хотите использовать тестовую консоль, а шлюз Управление API изолирован от сети или не разрешает трафик из прокси-сервера CORS.

Сведения об отладке API см. в руководстве по отладке API с помощью трассировки запросов.

Дополнить другими API

Вы можете создавать API из API, предоставляемых различными службами, в том числе:

Спецификация OpenAPI
SOAP API (интерфейс программирования приложений на основе SOAP)
A GraphQL API
Веб-приложение, размещенное в службе приложений Azure
Функции Azure
Приложения логики Azure
Azure Service Fabric

Примечание.

При импорте API операции добавляются к текущему API.

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

Перейдите к инстансу службы Управление API Azure на портале Azure.
Выберите API на странице обзора или выберите API> в меню слева.
Выберите многоточие (...) рядом с API, к которому требуется добавить другой API.
Выберите Импорт в раскрывающемся меню:
Выберите службу, из которой следует импортировать API.

Поделиться через