Importación de una especificación OpenAPI

SE APLICA A: Todos los niveles de API Management

En este artículo se muestra cómo importar una API de back-end de especificación de OpenAPI a Azure API Management mediante varias herramientas. En el artículo también se muestra cómo probar la API en API Management. Para obtener información sobre la compatibilidad con la versión de OpenAPI, consulte Restricciones de importación de API y problemas conocidos.

En este artículo aprenderá a:

• Importación de una especificación de OpenAPI mediante Azure Portal, la CLI de Azure o Azure PowerShell
• Prueba de la API en Azure Portal

Requisitos previos

• Una instancia de API Management Si aún no tiene una, realice el inicio rápido siguiente: Crear una instancia de Azure API Management.

• CLI de Azure

  • Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Introducción a Azure Cloud Shell.

    

  • Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, consulte Ejecución de la CLI de Azure en un contenedor de Docker.

    • Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Para finalizar el proceso de autenticación, siga los pasos que aparecen en su terminal. Para ver otras opciones de inicio de sesión, consulte Autenticación en Azure mediante la CLI de Azure.

    • En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para obtener más información sobre las extensiones, consulte Uso y administración de extensiones con la CLI de Azure.

    • Ejecute la versión de zona de disponibilidad para encontrar la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

• Azure PowerShell

  • Si opta por usar Azure PowerShell en un entorno local:
    • Instale la versión más reciente del módulo Az de PowerShell.
    • Conéctese a su cuenta de Azure mediante el cmdlet Connect-AzAccount.
  • Si decide usar Azure Cloud Shell:
    • Para más información, consulte Introducción a Azure Cloud Shell.

Importación de una API de back-end

En este ejemplo, importará la especificación OpenAPI para la API de Petstore de código abierto. Puede sustituir una especificación openAPI de su elección.

Portal

1. Vaya a la instancia de API Management en Azure Portal.

2. En el menú izquierdo, seleccione API>+ Agregar API.

3. En Crear a partir de la definición, seleccione OpenAPI.

   

4. Escriba los valores de la API. Puede establecer los valores durante la creación o luego accediendo a la pestaña Ajustes. Los valores de configuración se explican en el tutorial Importación y publicación de la primera API.

5. Seleccione Crear.

CLI de Azure

En el ejemplo siguiente se usa el comando az apim api import para importar una especificación de OpenAPI de la dirección URL especificada en una instancia de API Management que se denomina apim-hello-world. Para importar con una ruta de acceso a una especificación en lugar de una dirección URL, use el parámetro --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

Después de importar la API, puede actualizar la configuración mediante el comando az apim api update .

PowerShell

En el ejemplo siguiente se usa el cmdlet de Azure PowerShell Import-AzApiManagementApi para importar una especificación de OpenAPI de la dirección URL especificada en una instancia de API Management que se denomina apim-hello-world. Para importar con una ruta de acceso a una especificación en lugar de una dirección URL, use el parámetro -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

Después de importar la API, puede actualizar la configuración mediante el cmdlet Set-AzApiManagementApi .

Visualización y edición de una especificación OpenAPI

En Azure Portal, use el editor de especificaciones de OpenAPI para ver, validar o editar la especificación de la API que importó.

Para usar el editor de especificaciones OpenAPI:

1. Vaya a la instancia de API Management en Azure Portal.
2. En el menú de la izquierda, en API, seleccione API><su API>>Todas las operaciones.
3. En la pestaña Diseño, en Front-end, seleccione el editor de especificaciones OpenAPI (icono de lápiz). Puede abrir la especificación en formato JSON o YAML.
4. Revise o edite la especificación según sea necesario. Guarde los cambios.

Validación con un esquema de especificación OpenAPI

Puede configurar directivas de validación de API Management para validar solicitudes y respuestas o sus elementos contra el esquema en una especificación de OpenAPI. Por ejemplo, use la directiva validate-content para validar el tamaño o el contenido de una solicitud o cuerpo de respuesta.

Prueba de la nueva API en el portal

Puede llamar a operaciones directamente desde Azure Portal, lo que proporciona una manera cómoda de ver y probar las operaciones de una API.

1. Seleccione la API que creó en los pasos anteriores.

2. Seleccione la pestaña Prueba.

3. Seleccione una operación.

   La página muestra los campos de parámetros de consulta y los campos para los encabezados.

   Nota:

   En la consola de prueba, API Management rellena automáticamente un encabezado Ocp-Apim-Subscription-Key y configura la clave de suscripción de la suscripción de acceso completo integrada. Esta clave permite el acceso a todas las API de la instancia de API Management. Opcionalmente, se puede mostrar el encabezado Ocp-Apim-Subscription-Key si se selecciona el icono de ojo situado junto a la Solicitud HTTP.

4. En función de la operación, escriba los valores de los parámetros de consulta, los valores de encabezado o el cuerpo de la solicitud. Selecciona Enviar.

   Cuando la prueba se realiza correctamente, el back-end responde con un código de respuesta HTTP correcto y algunos datos.

   Sugerencia

   De forma predeterminada, la consola de prueba envía una solicitud al proxy CORS de API Management, que reenvía la solicitud a la instancia de API Management, que la reenvía al back-end. Este proxy usa la dirección IP pública 13.91.254.72 y solo puede acceder a los puntos de conexión públicos.

   Si desea enviar una solicitud directamente desde el explorador al servicio API Management, seleccione Omitir proxy CORS. Use esta opción si desea usar la consola de prueba y la puerta de enlace de API Management está aislada de red o no permite el tráfico desde el proxy CORS.

Para depurar una API, consulte Tutorial: Depuración de las API con el seguimiento de solicitudes.

Anexión de otras API

Puede crear una API fuera de las API expuestas por diferentes servicios, entre las que se incluyen:

• Especificación de OpenAPI
• Una API SOAP
• Una API de GraphQL
• Una aplicación web hospedada en Azure App Service
• Funciones de Azure
• Azure Logic Apps
• Azure Service Fabric

Nota:

Al importar una API, las operaciones se anexan a la API actual.

Para anexar una API a una API existente:

1. Vaya a la instancia de Azure API Management en Azure Portal:

   

2. Seleccione API en la página Información general o seleccione API >API en el menú de la izquierda.

   

3. Seleccione los puntos suspensivos (...) junto a la API que desea anexar a otra API.

4. Seleccione Importar en el menú contextual:

   

5. Seleccione un servicio desde el que se va a importar una API.

Contenido relacionado

• Limitaciones de importación de API
• Importación de una especificación OpenAPI
• Importación de una API de SOAP
• Importar una API de SOAP y convertir en REST
• Importación de una API de App Service
• Importación de una API de aplicación de contenedor
• Importación de una API de WebSocket
• Importación de una API de GraphQL
• Importación de un esquema GraphQL y configuración de solucionadores de campos
• Importación de una API de aplicación de funciones
• Importación de una API de aplicación lógica
• Importación de un servicio Service Fabric
• Importación de una API de Microsoft Foundry
• Importación de una API de Azure OpenAI
• Importación de una API de LLM
• Importación de una API de OData
• Exportación de una API REST como servidor MCP
• Exposición de un servidor MCP existente
• Importación de una API de agente de A2A
• Importación de metadatos de SAP OData
• Importación de una API de gRPC
• Edición de una API