Gobierno de API

Editar en línea

La herramienta API Governance valida los documentos de OpenAPI en función de conjuntos de reglas espectrales.

Esta herramienta se proporciona para que las capacidades de gobierno de la API de API Connect puedan utilizarse desde API Agent. Por ejemplo, validando los documentos de OpenAPI con conjuntos de reglas espectrales. Además, también puede utilizarse para corregir (remediar) los resultados de la validación espectral en un documento OpenAPI 3.0.

Detalles y limitaciones de la herramienta

A continuación se presentan los detalles y limitaciones de la herramienta API Governance:
  • Para utilizar esta herramienta con instalaciones locales de API Connect, active API Governance en el CR de gestión.
  • Actualmente, la herramienta de gobernanza de API permite trabajar con las versiones más recientes de los conjuntos de reglas en el servicio de gobernanza de API. Por ejemplo, puede validar un documento OpenAPI con la versión más reciente de un conjunto de reglas. Sin embargo, no se puede especificar una versión anterior cuando se utiliza prompt. Esta limitación también se aplica a la operación de corrección de los resultados de validación de un documento OpenAPI.
  • La operación de remediación (con conjuntos de reglas) de esta herramienta utiliza remediación basada en IA y puede llevar algún tiempo. Este tiempo se alarga en el caso de documentos más grandes y complejos: OpenAPI. Se aplica un tiempo de espera por defecto de tres minutos. Si la corrección tarda más de tres minutos en un documento de OpenAPI, la herramienta se desconecta.
  • Para adaptarse a la duración máxima de tres minutos de la reparación, asegúrese de que la configuración del controlador de entrada, la ruta de entrada o el tiempo de espera de HAProxy de su clúster no se agote en menos de tres minutos.
Las siguientes funciones del gobierno de la API están disponibles en API Agent:

Lista de reglas

Puede enumerar los conjuntos de reglas espectrales que se le proporcionan como parte de la Gobernanza de API dentro de su organización proveedora.

Una tabla muestra los siguientes detalles sobre los conjuntos de reglas:
  • Nombre
  • Versión
  • Descripción
Ejemplo
List rulesets
Próxima acción sugerida
  • Validación de la api {@filename} mediante el conjunto de reglas {ruleset}
  • Validación de la api {draft-api-name} : {draft-api-version} mediante el conjunto de reglas {ruleset}

Listar reglas en un conjunto de reglas

Puede enumerar todas las reglas individuales que forman parte de los conjuntos de reglas espectrales disponibles en su organización proveedora.

  • Una tabla muestra los siguientes detalles sobre cada regla dentro del conjunto de reglas especificado:
    • Nombre
    • Descripción
Tabla 1. Parámetros
Parámetro Obligatorio Descripción Valor predeterminado
ruleset Sí El nombre del conjunto de reglas cuyas reglas desea listar. Ninguna
Ejemplos de indicaciones
List rules in ruleset {ruleset}
Próxima acción sugerida
  • Validación de la api {@filename} mediante el conjunto de reglas {ruleset}
  • Validación de la api {draft-api-name} : {draft-api-version} mediante el conjunto de reglas {ruleset}

Validación de un documento OpenAPI mediante conjuntos de reglas

Puede validar documentos de OpenAPI con conjuntos de reglas espectrales en su organización de proveedores con las siguientes opciones:
  • Uso de una carga local de archivos adjuntos en la ventana de chat del complemento Visual Studio Code.
  • Proporcionar el nombre y la versión de un borrador de API existente dentro de la organización proveedora del usuario en el Gestor de API.

Esta operación muestra los siguientes detalles:

  • Breve resumen del número de hallazgos espectrales y su gravedad.
  • Un informe de validación. Un archivo. CSV que se puede descargar y que contiene el conjunto completo de los siguientes resultados:
    • Regla y conjunto de reglas de la regla
    • Mensaje que describe el hallazgo de validación que infringe la norma.
    • El número de línea del documento OpenAPI corresponde a la constatación.
    • Ubicación (ruta JSON) del hallazgo dentro del documento OpenAPI.
  • Los resultados y sus ubicaciones también se abren en el panel PROBLEMAS, como se muestra en la siguiente captura de pantalla.

  • Si el documento OpenAPI es un archivo local, se abre automáticamente en el editor de archivos Visual Studio Code. Todos los resultados espectrales están resaltados en el archivo.
Tabla 2. Parámetros
Parámetro Obligatorio Descripción Valor predeterminado
input_file Nee La especificación OpenAPI en formato YAML o JSON que debe validarse. Ninguna
api_name Nee El nombre (info.x-ibm-name) del proyecto de API que debe validarse. Ninguna
api_version Nee La versión (info.version) del proyecto de API que debe validarse. Ninguna
ruleset Sí Lista de conjuntos de reglas que se utilizarán en la validación. Ninguna
Ejemplos de indicaciones
Para validar un archivo local con un único conjunto de reglas, ejecute el siguiente comando:
validate api {@filename} using {ruleset} ruleset
Para validar un archivo local con respecto a dos o más conjuntos de reglas, ejecute la siguiente consulta
Validate api {@filename} using rulesets {ruleset-1}, {ruleset-2}
Para validar un borrador de API con un único conjunto de reglas, ejecute la siguiente consulta
Validate api {api-name}:{api-version} using {ruleset} ruleset
Para validar un borrador de API con varios conjuntos de reglas, ejecute el siguiente comando
Validate api {api-name}:{api-version} using Rulesets {ruleset-1}, {ruleset-2}
Próxima acción sugerida
  • Remediar api {@filename} mediante el uso de conjunto de reglas {ruleset}
  • Revalidar api {@filename} mediante conjunto de reglas {ruleset}

O

  • Remediate api {draft-api-name} : {draft-api-version} by using ruleset {ruleset}
  • Revalidar api {draft-api-name} : {draft-api-version} mediante conjunto de reglas {ruleset}

Remediar (arreglar) un documento OpenAPI que utiliza conjuntos de reglas

Si la validación de Gobernanza de API de un documento OpenAPI revela hallazgos basados en conjuntos de reglas espectrales dentro de su organización de proveedores, puede utilizar la corrección basada en IA para intentar resolver estos hallazgos. Cargue un archivo local en la ventana de chat del complemento Visual Studio Code o especifique un borrador de API existente en el Gestor de API.

Esta operación muestra los siguientes detalles:

  • Un archivo de documento OpenAPI que puede descargarse y que contiene todas las correcciones aplicadas que la corrección basada en IA pudo corregir automáticamente para los conjuntos de reglas elegidos.

  • Además, el archivo del documento OpenAPI corregido se abre automáticamente en el editor de archivos Visual Studio Code. Las correcciones aplicadas se resaltan directamente en el archivo.

  • Los siguientes detalles de cada corrección aplicada se muestran en el panel RECOMENDACIONES AI :

    • Ruta (ruta JSON) a la recomendación
    • Recomendación (una descripción)
    • Explicación (explica la recomendación)
    • Detalles de la regla espectral de la que procede la recomendación (gravedad, nombre del conjunto de reglas, nombre de la regla y mensaje).
Nota:
  • La corrección basada en IA sólo es compatible con los conjuntos de reglas spectral-owasp y spectral-oas de API Governance. Si se le pide que corrija utilizando un conjunto de reglas no admitido, recibirá una advertencia de que el conjunto de reglas no admitido no se utilizó en la respuesta de chat de API Agent.
  • La herramienta espera que se utilice como entrada un documento OpenAPI 3.0 válido. No se emite ninguna advertencia si se suministra un archivo no válido. Por ejemplo, si se introduce un documento AsyncAPI en un conjunto de reglas que se aplican a un documento OpenAPI, y viceversa.
  • Puede ejecutar la corrección varias veces en el mismo documento OpenAPI para corregir un problema si no se encuentra inicialmente.
  • La aplicación de correcciones mediante IA puede introducir nuevas infracciones de otras reglas espectrales, ya que el sistema no valida automáticamente sus correcciones y recomendaciones con respecto a los conjuntos de reglas después de cada cambio.
Tabla 3. Parámetros
Parámetro Obligatorio Descripción Valor predeterminado
input_file Nee La especificación OpenAPI en formato YAML o JSON que debe corregirse. Ninguna
api_name Nee El nombre (info.x-ibm-name) del proyecto de API que debe corregirse. Ninguna
api_version Nee La versión (info.version) del proyecto de API que debe corregirse. Ninguna
ruleset Sí Lista de conjuntos de reglas que se utilizarán en la corrección. Ninguna
Ejemplos de indicaciones
Para remediar un archivo local contra un conjunto de reglas, ejecute la siguiente solicitud:
Remediate api {@filename} using {ruleset} ruleset
Para remediar un archivo local contra dos o más conjuntos de reglas, ejecute la siguiente solicitud:
Remediate api {@filename} using rulesets {ruleset-1}, {ruleset-2}
Para remediar un borrador de API contra un único conjunto de reglas, ejecute la siguiente solicitud:
Remediate api {api-name}:{api-version} using {ruleset} ruleset
Para remediar un borrador de API contra múltiples conjuntos de reglas, ejecute la siguiente solicitud:
Remediate api {api-name}:{api-version} using Rulesets {ruleset-1}, {ruleset-2}
Próxima acción sugerida
  • Reremediate api {@filename} using ruleset {ruleset}
  • Validación de la api {@filename} mediante el conjunto de reglas {ruleset}

O

  • Reremediate api {draft-api-name} : {draft-api-version} using ruleset {ruleset}
  • Validación de la api {draft-api-name} : {draft-api-version} mediante el conjunto de reglas {ruleset}