Introducción a la extensión Azure API Center para Visual Studio Code (versión preliminar)
Para crear, descubrir, probar y consumir API en su Centro de API, puede utilizar la extensión del centro de API de Azure en su entorno de desarrollo Visual Studio Code:
Cree API: haga que otros puedan descubrir las API que está creando al registrarlas en su centro de API. Comprobación de la conformidad del diseño de la API Shift-left en Visual Studio Code con soporte integrado de linting. Asegúrese de que las nuevas versiones de API no interrumpan a los consumidores de API con la detección de cambios importantes.
Descubra las API: explore las API de su centro de API y consulte sus detalles y documentación.
Probar las API: utilice la interfaz de usuario Swagger o el cliente REST para explorar las solicitudes y respuestas de las API.
Consumir las API: genera clientes API SDK para su lenguaje favorito, incluidos JavaScript, TypeScript, .NET, Python y Java, utilizando el motor Microsoft Kiota que genera SDK para Microsoft Graph, GitHub y más.
Nota:
La extensión del centro de API para Visual Studio Code está en su versión preliminar. Obtenga más información sobre la versión preliminar de la extensión.
Requisitos previos
Uno o más centros de API en su suscripción Azure. Si aún no ha creado uno, consulte Inicio rápido: Creación del centro de API.
Actualmente, para acceder a los centros de API con la extensión es necesario tener asignado el rol de Colaborador o permisos superiores.
Las siguientes extensiones de Visual Studio Code son opcionales y necesarias solo para determinados escenarios, tal y como se indica:
- Extensión de cliente REST: para enviar peticiones HTTP y ver las respuestas en Visual Studio Code directamente
- Extensión Microsoft Kiota: para generar clientes API
- Extensión espectral: para ejecutar comprobaciones de conformidad de diseño de API de desplazamiento a la izquierda en Visual Studio Code
- CLI de Optic: para detectar cambios importantes entre los documentos de especificación de API.
Configurar
- Instale la extensión Azure API Center para Visual Studio Code desde Visual Studio Code Marketplace. Instale las extensiones opcionales que necesite.
- En Visual Studio Code, en la barra de actividades de la izquierda, seleccione Centro de API.
- Si no ha iniciado sesión en su cuenta Azure, seleccione Iniciar sesión en Azure... y siga las instrucciones para iniciar sesión. Seleccione una cuenta Azure con el Centro de API (o centros de API) desde el que desea ver las API. También puede filtrar por suscripciones específicas si tiene muchas para ver.
Registro de API
Registre una API en su centro de API directamente desde Visual Studio Code, ya sea registrándola como una operación única o con una canalización CI/CD.
- Utilice la combinación de teclas Ctrl+Mayús+P para abrir la paleta de comandos. Escriba Azure API Center: Registrar API y pulse Intro.
- Seleccione cómo desea registrar su API en su centro API:
- Paso a paso es lo mejor para el registro único de API.
- CI/CD agrega una canalización pre configurada de GitHub o Azure DevOps a su área de trabajo activa de Visual Studio Code que se ejecuta como parte de un flujo de trabajo de CI/CD en cada confirmación al control de origen. Se recomienda inventariar las API con su centro de API mediante CI/CD para garantizar que los metadatos de la API, incluidas la especificación y la versión, se mantienen actualizados en su centro de API a medida que la API sigue evolucionando con el tiempo.
- Complete los pasos de registro:
- Para Paso a paso, seleccione el centro de API en el que desea registrar las API y responda a las preguntas con información como el título de la API, el tipo, la fase del ciclo de vida, la versión y la especificación para completar el registro de la API.
- Para CI/CD, seleccione GitHub o Azure DevOps, en función del mecanismo de control de código fuente que prefiera. Debe estar abierta un área de trabajo de Visual Studio Code para que la extensión del Centro API agregue una canalización a tu área de trabajo. Una vez agregado el archivo, complete los pasos documentados en el propio archivo de canalización de CI/CD para configurar las variables de entorno y la identidad de Azure Pipeline/Acciones de GitHub. Al enviarla al control de código fuente, la API se registrará en su Centro de API.
Conformidad con el diseño de la API
Para garantizar la conformidad del diseño con las normas de la organización a medida que crea API, la extensión del Centro de API de Azure para Visual Studio Code proporciona compatibilidad integrada para la depuración de especificaciones de API con Spectral.
- Utilice la combinación de teclas Ctrl+Mayús+P para abrir la paleta de comandos. Escriba Azure API Center: Establecer guía de estilo de API activa y pulse Intro.
- Seleccione una de las reglas predeterminadas proporcionadas o, si su organización ya dispone de una guía de estilo, utilice Seleccionar archivo local o Introducir URL remota para especificar el conjunto de reglas activo en Visual Studio Code. Pulse Intro.
Una vez establecida una guía de estilo de API activa, al abrir cualquier archivo de especificación basado en OpenAPI o AsyncAPI se activará una operación de linting local en Visual Studio Code. Los resultados se muestran tanto en línea en el editor, como en la ventana Problemas (Ver>Problemas o Ctrl+Mayús+M).
Detección de cambios importantes
Al introducir nuevas versiones de la API, es importante asegurarse de que los cambios introducidos no interrumpen a los consumidores de la API en versiones anteriores de la API. La extensión del Centro de API de Azure para Visual Studio Code lo facilita con la detección de cambios importantes para los documentos de especificación de OpenAPI con tecnología de Optic.
- Utilice la combinación de teclas Ctrl+Mayús+P para abrir la paleta de comandos. Escriba Centro de API de Azure: detectar cambio importante y presione Entrar.
- Seleccione el primer documento de especificación de API que se va a comparar. Entre las opciones válidas se incluyen las especificaciones de API que se encuentran en el centro de API, un archivo local o el editor activo en Visual Studio Code.
- Seleccione el segundo documento de especificación de API que se va a comparar. Entre las opciones válidas se incluyen las especificaciones de API que se encuentran en el centro de API, un archivo local o el editor activo en Visual Studio Code.
Visual Studio Code abrirá una vista de diferencias entre las dos especificaciones de API. Los cambios importantes se muestran tanto en línea en el editor como en la ventana Problemas (Ver>Problemas o Ctrl+Mayús+M).
Detección de API
Los recursos de su centro API aparecen en la vista de árbol de la izquierda. Amplíe un recurso del centro de API para ver las API, las versiones, las definiciones, los entornos y las implementaciones.
Busque API dentro de un centro de API mediante el icono de búsqueda que se muestra en el elemento de vista árbol de Apis.
Ver la documentación de la API
Puede consultar la documentación de una definición de API en su centro de API y probar las operaciones de la API. Esta función solo está disponible para las API basadas en OpenAPI en su centro de API.
Expanda la vista de árbol del centro de API para mostrar una definición de API.
Haga clic con el botón derecho del ratón en la definición y seleccione Abrir documentación de la API. Aparece una nueva pestaña con la interfaz Swagger para la definición de la API.
Para probar la API, seleccione un punto de conexión, seleccione Probar, introduzca los parámetros necesarios y seleccione Ejecutar.
Nota:
Dependiendo de la API, es posible que tenga que proporcionar credenciales de autorización o una clave de API para probar la API.
Generación de un archivo HTTP
Puede ver un archivo .http basado en la definición de API en su centro de API. Si la extensión REST Client está instalada, puede realizar peticiones de directorio desde el editor de código de Visual Studio. Esta función solo está disponible para las API basadas en OpenAPI en su centro de API.
Expanda la vista de árbol del centro de API para mostrar una definición de API.
Haga clic con el botón derecho en la definición y seleccione Generar archivo HTTP. Aparece una nueva pestaña que muestra un documento .http con la especificación de la API.
Para realizar una solicitud, seleccione un punto de conexión y elija Enviar solicitud.
Nota:
Dependiendo de la API, es posible que tenga que proporcionar credenciales de autorización o una clave de API para realizar la solicitud.
Generar cliente API
Utilice la extensión Microsoft Kiota para generar un cliente API para su idioma favorito. Esta función solo está disponible para las API basadas en OpenAPI en su centro de API.
- Expanda la vista de árbol del centro de API para mostrar una definición de API.
- Haga clic con el botón derecho en la definición y seleccione Generar cliente API. Aparecerá el panel del Generador OpenAPI de Kiota.
- Seleccione los puntos de conexión de la API y las operaciones HTTP que desea incluir en sus SDK.
- Seleccione Generar cliente API.
Introduzca los detalles de configuración sobre el nombre del SDK, el espacio de nombres y el directorio de salida.
Seleccione el idioma para el SDK generado.
Se genera el cliente.
Para obtener más detalles sobre el uso de la extensión Kiota, consulte Extensión Microsoft Kiota para Visual Studio Code.