Compartir a través de

Análisis de las API en el Centro de API: Administrado por Microsoft

  • Artículo

El Centro de API de su organización incluye capacidades de análisis de datos integradas administradas por Microsoft (vista previa) para analizar las definiciones de API y verificar su cumplimiento con las reglas de estilo organizacional, generando informes individuales y resumidos. El análisis de API identifica y ayuda a corregir errores e incoherencias comunes en las definiciones de API.

Con el análisis de API:

  • El Centro de API de Azure analiza automáticamente las definiciones de API siempre que agregue o actualice una definición de API. Las definiciones de API se linen de forma predeterminada con un spectral:oas ruleset (guía de estilo de API).
  • Los informes de análisis de API se generan en Azure Portal, en el que se muestra cómo las definiciones de API se ajustan a la guía de estilo.
  • Puede usar la extensión del Centro de API de Azure para Visual Studio Code para personalizar y probar su propia guía de estilo de API localmente y, a continuación, implementarla en el centro de API.

Importante

Si lo prefiere, puede habilitar el análisis y el control de linting autoadministrados mediante una función de Azure personalizada, anulando las capacidades integradas. Deshabilitar cualquier función que se use para la linting autoadministrada antes de usar el análisis de API administrada.

Limitaciones

  • Actualmente, solo se analizan los documentos de especificación OpenAPI y AsyncAPI en formato JSON o YAML.
  • Actualmente, al configurar un único conjunto de reglas, se aplica a todas las definiciones de OpenAPI de la instancia de API Center.
  • Hay límites para el número máximo de definiciones de API analizadas. El análisis puede tardar entre unos minutos hasta 24 horas en completarse.

Requisitos previos

Visualización de informes de análisis de API

Puede ver un resumen del análisis y los informes del análisis de las definiciones de API en Azure Portal. Después de analizar las definiciones de API, el informe enumera los errores, las advertencias y la información en función de la guía de estilo de API configurada.

En el informe de análisis de API, revise también el conjunto de reglas que se usó para el análisis y el historial de pasos de linting.

Para ver un resumen del análisis en API Center:

  1. En el portal, vaya al centro de API.

  2. En el menú de la izquierda, en Gobernanza, seleccione Análisis de API. Aparece el resumen.

    Captura de pantalla del resumen del análisis de API en el portal.

  3. Opcionalmente, seleccione el icono del informe de análisis de API para una definición de API. Aparece el informe de análisis de API de la definición, como se muestra en el recorte de pantalla siguiente.

    Captura de pantalla de un informe de análisis de API en el portal.

    Sugerencia

    También puede ver el informe de análisis de API seleccionando Análisis en la barra de menús de la definición de API.

Personalización del conjunto de reglas

Puede usar la extensión del Centro de API de Azure para Visual Studio Code para personalizar el conjunto de reglas predeterminado para el centro de API o reemplazarlo como guía de estilo de API de la organización. Por ejemplo, puede extender el conjunto de reglas o agregar funciones personalizadas.

Para personalizar o reemplazar el conjunto de reglas:

  1. En Visual Studio Code, seleccione el icono de Azure API Center en la barra de actividades.
  2. Abra la carpeta .api-center-rules en la raíz de la carpeta de trabajo.
  3. En la carpeta del recurso del centro de API, abra el archivo ruleset.yml.
  4. Modifique o reemplace el contenido según sea necesario.
  5. Guarde los cambios en ruleset.yml.

Prueba local del conjunto de reglas

Antes de implementar el conjunto de reglas personalizado en la instancia de API Center, valídelo de forma local. La extensión de Azure API Center para Visual Studio Code proporciona compatibilidad integrada con el linting de especificaciones de API con Spectral.

  1. En Visual Studio Code, utilice la combinación de teclas Ctrl+Mayús+P para abrir la paleta de comandos.

  2. Escriba Azure API Center: Establecer guía de estilo de API activa y pulse Intro.

  3. Elija Seleccionar archivo local y especifique el archivo ruleset.yml que ha personalizado. Pulse Intro.

    Este paso convierte el conjunto de reglas personalizado en la guía de estilo de API activa para el linting.

Ahora, al abrir un archivo de definición de API basado en OpenAPI, se desencadena automáticamente una operación de linting local en Visual Studio Code. Los resultados se muestran insertados en el editor y en la ventana Problemas (Ver > Problemas o Ctrl+Mayús+M).

Sugerencia

Los desarrolladores de API de su organización también pueden usar esta funcionalidad de linting local para ayudar a mejorar sus definiciones de API antes de registrar las API en el centro de API.

Recorte de pantalla del linting de una definición de API en Visual Studio Code.

Revise los resultados del linting. Realice los ajustes necesarios en el conjunto de reglas y continúe probándolo localmente hasta que funcione como desee.

Implementación del conjunto de reglas en la instancia de API Center

Para implementar el conjunto de reglas personalizado en la instancia de API Center:

  1. En Visual Studio Code, seleccione el icono de Azure API Center en la barra de actividades.
  2. En el panel de API Center, expanda el recurso de API Center en el que ha personalizado el conjunto de reglas.
  3. Haga clic con el botón derecho en Reglas y seleccione Implementar reglas en API Center.

Un mensaje le notificará una vez que las reglas se hayan implementado correctamente en la instancia de API Center. El motor de linting usa el conjunto de reglas actualizado para analizar las definiciones de API.

Para ver los resultados del linting con el conjunto de reglas actualizado, consulte los informes de análisis de API en el portal.

Contenido relacionado