Configuración de un recopilador de GitHub para Descubrimiento de API

Cómo añadir un recopilador de orígenes de datos de GitHub a la prestación Descubrimiento de API .

Antes de empezar

Para poder configurar un recopilador de descubrimiento de API GitHub , son necesarios los requisitos previos siguientes:

Debe tener un repositorio GitHub que contenga uno o más documentos de referencia de OpenAPI .

Se necesita uno de los siguientes roles de organización de proveedores para poder gestionar orígenes:

Administrador de la organización
Propietario (Owner)
Rol personalizado con el permiso Settings: Manage .

Acerca de esta tarea

API discovery es un complemento de IBM® API Connect que puede utilizarse para descubrir y añadir API a su proceso de desarrollo de API. Para poder descubrir cualquier API, debe configurar uno o más recopiladores de orígenes de datos. Estos recopiladores se agregan automáticamente a la pestaña Fuentes de la interfaz de usuario del Administrador de API cuando el recopilador envía los primeros documentos de OpenAPI a su organización proveedora.

Para configurar un recopilador de descubrimiento de API GitHub , cree un flujo de trabajo GitHub Acciones en el repositorio GitHub . Este flujo de trabajo permite que los documentos de referencia de OpenAPI se envíen automáticamente a, y se mantengan sincronizados con, API Connect. Estos documentos de OpenAPI se pueden copiar en borradores de API según sea necesario, para habilitar la gestión del ciclo de vida completo en Gestor de API.

Nota: Cuando se envía una API con una carga útil grande (por ejemplo, una API compleja de más de 1 MB de tamaño), puede haber algún retraso en la creación de la API descubierta. Se recomienda que no ejecute otro flujo de trabajo simultáneamente, hasta que vea que se ha creado una API en el servicio de descubrimiento de API .

Procedimiento

Para configurar un recopilador GitHub , realice los pasos siguientes.

Cree un directorio .github/workflows en su repositorio en GitHub (si ese directorio no existe).
En el directorio .github/workflows , cree un archivo para la acción de flujo de trabajo, por ejemplo, discover-api.yml.

En el archivo de acción de flujo de trabajo, copie el siguiente trabajo de flujo de trabajo.

El siguiente YAML contiene el flujo de trabajo para el trabajo run-discovery . En una confirmación push al repositorio GitHub este trabajo comprueba si hay cambios en los archivos o carpetas especificados y, si los hay, envía la diferencia git de los commits en los archivos a API Connect. API_FILES se puede cambiar a API_FOLDERS cuando es necesario descubrir una o más carpetas completas.

name: Sync Discovered API with APIConnect

on: [pull_request, workflow_dispatch, push]

env:
  API_HOST: <host-name>
  PLATFORM_API_PREFIX: <platform-api>
  PROVIDER_ORG: <porg-name>
  API_FILES: <file/files name>

jobs:
  run-discovery:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Difference
      id: difference-output
      run: |
        echo "action_updates=$(git diff --name-only --diff-filter=ACMRT ${{ github.event.before }} ${{ github.sha }} | xargs)" >> $GITHUB_OUTPUT
    - uses: ibm-apiconnect/apic-discovery-action@main
      id: discover-apis
      with:
        api_host: ${{ env.API_HOST }}
        platform_api_prefix: ${{ env.PLATFORM_API_PREFIX }}
        provider_org: ${{ env.PROVIDER_ORG }}
        api_key: ${{ secrets.apicApikey }}
        if: env.API_FILES
        api_files: ${{ env.API_FILES }}
        else if: env.API_FOLDERS
        api_folders: ${{ env.API_FOLDERS }}
        resync_check: ${{ true }}
        git_diff: ${{ steps.difference-output.outputs.action_updates }}
    - name: Display the action-result
      run: |
        echo "Result of the action: ${{ steps.discover-apis.outputs.action-result }}"
        echo "End"

Tenga en cuenta que, opcionalmente, también puede utilizar el siguiente archivo de flujo de trabajo check_changes_job . En una confirmación push al repositorio GitHub este trabajo comprueba si hay cambios en los archivos o carpetas especificados, o un cambio en el archivo discover-api.yml , y si los hay, envía los archivos a API Connect. API_FILES se puede cambiar a API_FOLDERS cuando es necesario descubrir una o más carpetas completas.

name: Sync Discovered API with APIConnect

on: [pull_request, workflow_dispatch, push]

env:
  API_HOST: <host-name>
  PLATFORM_API_PREFIX: <platform-api>
  PROVIDER_ORG: <porg-name>
  API_FILES: <file/files name>

jobs:
  check_changes_job:
    runs-on: 'ubuntu-20.04'
    # Declare outputs for next jobs
    outputs:
      action_changed: ${{ steps.check_workflow_changed.outputs.action_updates }}
      changed_filename: ${{ steps.changed_filename.outputs.api_file }}
      apifiles_env: ${{ steps.changed_filename.outputs.apifiles_env }}
      folder_changed: ${{ steps.check_apifolders_changed.outputs.folder_updates }}
    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 2
    - name: Check Workflow changed
      id: check_workflow_changed
      run: |
        echo "action_updates=$(git diff --name-only --diff-filter=ACMRT ${{ github.event.before }} ${{ github.sha }} | grep discover-api.yml | xargs)" >> $GITHUB_OUTPUT
    - name: Changed API File Name
      id: changed_filename
      run: |
        echo "api_file=$(git diff --name-only --diff-filter=ACMRT ${{ github.event.before }} ${{ github.sha }} | xargs)" >> $GITHUB_OUTPUT
        echo "apifiles_env=$(echo $API_FILES)" >> $GITHUB_OUTPUT
    - name: Check API Folders changed
      id: check_apifolders_changed
      run: |
        echo "folder_updates=$(git diff --name-only --diff-filter=ACMRT ${{ github.event.before }} ${{ github.sha }} | grep $API_FOLDERS | xargs)" >> $GITHUB_OUTPUT
  run-discovery:
    runs-on: ubuntu-latest
    needs: [ check_changes_job ]
    if: ${{ (contains(needs.check_changes_job.outputs.apifiles_env,needs.check_changes_job.outputs.changed_filename)) || (needs.check_changes_job.outputs.action_changed) || (needs.check_changes_job.outputs.folder_changed) }}
    steps:
    - uses: actions/checkout@v4
    - uses: ibm-apiconnect/apic-discovery-action@main
      id: discover-apis
      with:
        api_host: ${{ env.API_HOST }}
        platform_api_prefix: ${{ env.PLATFORM_API_PREFIX }}
        provider_org: ${{ env.PROVIDER_ORG }}
        api_key: ${{ secrets.apicApikey }}
        if: env.API_FILES
        api_files: ${{ env.API_FILES }}
        else if: env.API_FOLDERS
        api_folders: ${{ env.API_FOLDERS }}
        resync_check: ${{ needs.check_changes_job.outputs.action_changed && true || false }}
    - name: Display the action-result
      run: |
        echo "Result of the action: ${{ steps.discover-apis.outputs.action-result }}"

Donde:

name es el nombre del flujo de trabajo GitHub Action.
API_HOST es el nombre de dominio de la instancia de API Connect donde se enviarán las API descubiertas. Por ejemplo, us-east-a.apiconnect.automation.ibm.com.
PLATFORM_API_PREFIX tiene un valor predeterminado de platform-api. Puede cambiarlo para que coincida con la configuración del sistema, si es diferente.
INSECURE_SKIP_TLS_VERIFY si se establece en true, esta acción omite la comprobación de validez del certificado de servidor. Esta acción puede ser necesaria si el sistema API Connect utiliza certificados autofirmados. Tenga en cuenta que si establece esta acción en " true ", sus conexiones de HTTPS no serán seguras.
PROVIDER_ORG es el nombre de la organización de proveedores de API Connect .
API_FILES o API_FOLDERS especifica si desea que se tengan en cuenta uno o varios archivos o carpetas de API para la acción de flujo de trabajo. Separe varios archivos o carpetas utilizando una coma, por ejemplo, mail-api.yaml,my-api.json,APIfolder/pet-exp.json. Los archivos de API pueden estar en formato json o yaml .
resync_check indica si los cambios en la acción, como en la creación inicial, deben desencadenar una sincronización de api-file.
git_diff comprueba la diferencia entre la confirmación actual y la anterior. Si varios archivos han cambiado en la confirmación, el flujo de trabajo sólo se ejecuta si uno o más de los archivos que se suministran en API_FILES o API_FOLDERS ha cambiado.
api_key son las credenciales necesarias para enviar archivos de API al Gestor de API. Puede obtener la clave de API del usuario que tiene acceso al Gestor de API para publicar las API. Para obtener información sobre cómo obtener una clave API, consulta «Gestión de claves API REST de la plataforma ». A continuación, debe almacenar la clave de API en un secreto de GitHub , que luego puede utilizar este flujo de trabajo de acción GitHub . En el YAML de este paso, api_key se denomina apicApikey, por lo que si desea reutilizar este YAML , asegúrese de crear el secreto con el mismo nombre. Para obtener información sobre cómo almacenar claves API como secretos en las acciones de GitHub, consulta Using secrets in GitHub Actions la documentación de GitHub.

Para obtener más información sobre el apic-discovery-action, y sobre cómo utilizarlo, consulta apic-discovery-action y apic-discovery-test en github.com. Estos recursos de API Connect incluyen ejemplos de trabajo con un repositorio de prueba.

Confirme el archivo de flujo de trabajo en una rama del repositorio GitHub .
La confirmación del archivo de flujo de trabajo desencadena un suceso push y ejecuta el flujo de trabajo de sincronización con API Connect.
En la interfaz de usuario de API Manager, haga clic en el icono Descubrir y, a continuación, haga clic en la pestaña Fuentes para ver su GitHub recopilador.
Los orígenes pueden tener el estado siguiente:
- Habilitado : el origen está habilitado y se sincroniza con el recopilador de acuerdo con su configuración.
- Inhabilitado : el origen está inhabilitado y API Connect no aceptará ningún archivo del recopilador. Este estado lo establece el servicio de descubrimiento si falla una operación de descubrimiento.
- No en buen estado : el recopilador de origen no está disponible.
- En pausa : el origen está en pausa y API Connect no aceptará ningún archivo del recopilador.
Opcional: puedes hacer clic en el icono de opciones situado junto a una fuente para cambiar su estado.
- Detener recopilador : para poner en pausa el origen.
- Suprimir recopilador : para suprimir el origen de la interfaz de usuario de API Manager . Los archivos de origen externos no se suprimen.
- Reanudar recopilador : para reiniciar un origen en pausa o inhabilitado.
Opcional: puedes hacer clic en el icono «Gestionar columnas» situado en el encabezado de la tabla para cambiar el orden y la vista de las columnas.

Resultados

El recopilador de orígenes de datos de GitHub ya está preparado para sincronizarse con API Connect. Cuando el recopilador envía los primeros documentos de OpenAPI a la organización de proveedores, el recopilador se lista en el separador Orígenes de la sección Descubrir de API Manager. Un recopilador de GitHub publica actualizaciones en API Connect solo cuando se detecta una diferencia debido a un suceso de confirmación o PR en el origen de datos original.

Qué hacer a continuación

Puede pulsar el separador API en la sección Descubrir de la interfaz de usuario de API Manager y revisar el tráfico de API en el origen de GitHub . Para obtener más información, consulte Revisar las API descubiertas.