Uso del Asistente de API para documentar sus API

Puede utilizar el componente de mejoras de especificación del Asistente de API para ayudarle a mejorar su documentación de API analizando su definición de API y generando recomendaciones para sus descripciones y ejemplos. Mejorar la especificación de su API acelera su adopción por parte de los consumidores.

El componente de mejora de la especificación utiliza el IBM watsonx Granite LLM models para ayudarle a construir sus APIs más rápido. Aproveche el Asistente de API para generar rápidamente descripciones y ejemplos claros y concisos para documentar sus definiciones de API.

Cómo utilizar el Asistente de API para generar ejemplos y descripciones de su API

Puede utilizar el Asistente de API mientras crea o edita una definición de API en la interfaz de usuario del Gestor de API. El Asistente de API revisa la definición de la API y sugiere descripciones y ejemplos para los campos del esquema. A continuación, puede elegir qué sugerencias desea que API Connect incorpore a su definición de API.

  1. Inicie sesión en API Connect Enterprise as a ServicePremium subscription.
  2. En Administrador de API, abra una OpenAPI 3.0 API que desee editar.
  3. En la pestaña Diseño, haga clic en el icono de la vista de fuentes (que es un pequeño cuadrado gris que contiene dos corchetes angulares que encierran una barra diagonal) para trabajar en la vista Fuente.
  4. Haga clic en el icono AI (que es un pequeño cuadrado gris con las letras AI y una flecha en negro) para abrir el panel del Asistente de API.
  5. Asegúrese de que el panel Ampliaciones de la especificación esté abierto y haga clic en Generar para solicitar sugerencias de IA para la descripción y los ejemplos de la API.
  6. Haga clic en Aplicar para cada sugerencia que desee incorporar a su API.

    Para aceptar rápidamente todas las sugerencias, haga clic en Aceptar todas.

  7. Haga clic en Guardar para guardar la definición de API actualizada.

Ejemplo: Mejora de la API de ejemplo EmployeesApi

En este ejemplo estamos utilizando un EmployeesApi para mostrar el flujo a través de la generación de algunas sugerencias de IA, la revisión de las sugerencias, y luego aplicarlas a la API. Puede seguir los pasos con su propia API.

  1. Inicie sesión en API Connect Enterprise as a ServicePremium subscription.

  2. En Administrador de API, haga clic en el icono Revelar (que es un pequeño cuadrado negro con el contorno de un lápiz blanco) Desarrollar para abrir la página de desarrollo de API y, a continuación, asegúrese de que la pestaña APIs está seleccionada para poder ver sus API.
    Abrir la página Desarrollar

  3. Seleccione una API de Tipo OpenAPI 3.0 (REST), y haga clic en su Título para editarla.
    Editar una OpenAPI 3.0 API

  4. La página Diseño se abre en la vista Formulario.

    Observe que en la API de ejemplo faltan descripciones de algunas propiedades.

    En la API de muestra faltan descripciones de propiedades

  5. Haga clic en el icono de la vista de fuentes (que es un pequeño cuadrado gris que contiene dos corchetes angulares que encierran una barra diagonal) para trabajar en la vista Fuente.

    API Assistant es más fácil de usar cuando puede ver el código fuente de su API.

    Utilice la vista Fuente para ver el código de la API
  6. Haga clic en el icono AI (que es un pequeño cuadrado gris con las letras AI y una flecha en negro) para abrir el panel del Asistente de API. Asegúrese de que está seleccionada la pestaña Mejoras de la especificación.
  7. En el panel de mejoras de la especificación, puede hacer clic en el icono AI explicada (que es el contorno de un pequeño cuadrado negro, que contiene las letras AI) para obtener más información sobre cómo el Asistente de API utiliza la IA para mejorar sus definiciones de API.
    Más información sobre el Asistente API

    Vuelve a hacer clic en el icono AI explicada (que es el contorno de un pequeño cuadrado negro, que contiene las letras AI) para cerrar la ventana emergente.

  8. Ahora haga clic en Generar para ver si se recomiendan algunas sugerencias de IA para su API.

    En nuestra API de ejemplo, el Asistente de API analiza la definición de API y devuelve texto sugerido para todas las descripciones y ejemplos vacíos.

    Haga clic en Generar y vea las sugerencias

    Observe los siguientes cambios en la pantalla:

    • El panel Asistente de API muestra el nombre de cada campo y la descripción o ejemplo sugeridos. Los valores correspondientes también se insertan y resaltan en el código fuente de la API para que pueda verlos en su sitio.

      Mientras el panel Asistente de API está abierto, el código fuente de la API está en modo de sólo lectura para evitar actualizaciones accidentales. Al cerrar el panel, el código vuelve a ser editable.

    • Si una propiedad ya contiene una descripción o un ejemplo, se conserva el valor existente. Por ejemplo, en nuestra API de ejemplo, la propiedad employeeNumber ya contiene una descripción de test, por lo que no se genera una sugerencia para ella.
    • En el menú Diseño, se muestran los iconos Sugerencia de AI y Icono Suprimir para cualquier sección de la definición de API que haya recibido sugerencias, de modo que pueda saltar fácilmente a esa sugerencia o eliminarla.
  9. Cuando esté preparado para aceptar o rechazar las sugerencias, realice una de las siguientes acciones:
    • Acepte todas las sugerencias:

      Haga clic en Aplicar todo para aceptar rápidamente todas las sugerencias.

    • Regenera todas las sugerencias:

      Haga clic en el icono Regenerar todo para regenerar todas las sugerencias que aún no se hayan aplicado.

    • Acepta una sugerencia:

      Haga clic en Aplicar para cada sugerencia que desee aceptar.

    • Borrar una sugerencia:

      Haga clic en Icono Suprimir para cada sugerencia que desee eliminar.

    Mientras trabajas con las sugerencias, fíjate en el siguiente comportamiento:

    • Cualquier sugerencia que aplique se añade a la definición de API, pero la definición en sí no se guarda hasta que haga clic en Guardar en la cabecera de la página.
    • Cuando haga clic en Guardar, se guardarán sus propios cambios y todas las sugerencias aplicadas; sin embargo, se perderán las sugerencias que no haya aplicado.
    • Si sale de la página Diseño de API antes de aplicar una sugerencia, ésta se perderá.
    • En cualquier momento, puede volver a editar la API y generar sugerencias para las descripciones y ejemplos vacíos.
  10. Haga clic en Icono Cerrar para cerrar el panel del Asistente de API.

  11. Vuelva a la vista Formulario haciendo clic en el icono de la vista de formulario (que es un pequeño cuadrado gris que contiene el contorno en negro de una hoja de papel con un lápiz).

    En la API de ejemplo, puede ver que los campos Descripción de las propiedades EmployeeBody contienen ahora las descripciones sugeridas.

    Las sugerencias aplicadas se añaden a la definición de la API

  12. Recuerde hacer clic en Guardar para guardar la definición de API actualizada.