Compartir vía

Habilitación del análisis de API en el centro de API: administrado por Microsoft

  • Artículo

En este artículo, se explica cómo habilitar el análisis de API en Azure API Center sin tener que administrarlo usted mismo (versión preliminar). El análisis de API ofrece funcionalidades de linting para analizar las definiciones de API en el Centro de API de la organización. Linting garantiza que las definiciones de API se adhieren a las reglas de estilo organizativo, lo que genera informes individuales y de resumen. Use el análisis de API para identificar y corregir errores comunes e incoherencias en las definiciones de API.

Importante

El análisis de API administrado en el Centro de API configura un motor de linting y las dependencias necesarias automáticamente. También puede habilitar el linting y el análisis de forma manual mediante una función personalizada de Azure. Deshabilite cualquier función que se use para la migración manual antes de habilitar el análisis de API administrado.

En este escenario:

  1. Agregue un conjunto de reglas de linting (guía de estilo de API) en API Center mediante la extensión de Visual Studio Code para Azure API Center.
  2. Azure API Center ejecuta automáticamente el linting al agregar o actualizar una definición de API. También se desencadena para todas las definiciones de API al implementar un conjunto de reglas en la instancia de API Center.
  3. Revise los informes de análisis de API en Azure Portal para ver cómo se ajustan las definiciones de API a la guía de estilo.
  4. Opcionalmente, personalice el conjunto de reglas para las API de la organización. Pruebe el conjunto de reglas personalizado localmente antes de implementarlo en la instancia de API Center.

Limitaciones

  • Actualmente, solo se analizan los documentos de especificación de OpenAPI en formato JSON o YAML.
  • De manera predeterminada, habilitará el análisis con el conjunto de reglas spectral:oas. Para obtener más información sobre las reglas integradas, consulte el repositorio de GitHub Spectral.
  • 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

Habilitación del análisis de API mediante Visual Studio Code

Para habilitar el análisis de API con el conjunto de reglas de linting predeterminado:

  1. En Visual Studio Code, abra una carpeta que usará para administrar los conjuntos de reglas de Azure API Center.

  2. Seleccione el icono de Azure API Center en la barra de actividades.

  3. En el panel de API Center, expanda el recurso de API Center en el que se va a habilitar el análisis de API.

  4. Haga clic con el botón derecho en Reglas y seleccione Habilitar análisis de API.

    Recorte de pantalla de la habilitación del linting y el análisis de API en Visual Studio Code.

Un mensaje le notificará una vez que el análisis de API esté habilitado correctamente. Se crea una carpeta para la instancia de API Center en .api-center-rules, en la raíz de la carpeta de trabajo. La carpeta de la instancia de API Center contiene:

  • Un archivo ruleset.yml que define la guía de estilo de API predeterminada que usa el motor de linting.
  • Una carpeta functions con una función personalizada de ejemplo que puede usar para ampliar el conjunto de reglas.

Con el análisis habilitado, el motor de linting analiza las definiciones de API de la instancia de API Center en función del conjunto de reglas predeterminado y genera informes de análisis de API.

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.

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 personalizar el conjunto de reglas predeterminado o sustituirlo por la guía de estilo de la 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, abra la carpeta .api-center-rules en la raíz de la carpeta de trabajo.
  2. En la carpeta del recurso de API Center, abra el archivo ruleset.yml.
  3. Modifique o reemplace el contenido según sea necesario.
  4. 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).

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