Deberá acceder al sitio de Apicurio de CONACYT.

Una vez autenticado, deberá dar clic en el botón para crear una nueva API (Create New API) y se le mostrará el siguiente formulario.

Elija API en blanco (Blank API) y llene los demás campos.

A continuación se le mostrará la siguiente pantalla:

Más adelante, para automatizar la publicación de la OAS, necesitará como colaborador al usuario de integración.

Para agregar a un colaborador, haga clic en el botón de tres puntos verticales para ver las opciones sobre la API y elija Colaborar (Collaborate...).

En la pantalla que se muestre haga clic en el botón "Invitar a un Colaborador" (Invite a Collaborator) y se le generará un enlace de invitación. Copie el enlace y hágalo llegar al administrador para que acepte colaborar con el usuario de integración.

Una vez que el administrador acepte verá a ese usuario además del suyo en la pantalla de colaboradores como se muestra a continuación:

Es posible editar la API en línea aunque se recomienda que permita que sea el pipeline de la integración continua quien publique estos cambios puesto que ya estarían reflejados en el código. Sin embargo, se muestra también este paso porque es posible que aún no cuente con ningún proyecto de implementación y desee en efecto utilizar esta función para diseñar su API.

Haga clic en el botón para editar API (Edit API).
Se le mostrará la siguiente pantalla para la edición de la API.

Utilice la vista de Diseño (Design) para especificar la API utilizando la interfaz gráfica de Apicurio o bien utilice la vista de Fuente (Source) si usted ya cuenta con una OAS en formato YAML o JSON para pegarla allí.

La idea de una herramienta como Apicurio es que muestre siempre la última versión de la API ya sea para ambiente de desarrollo, de producción o la cantidad de ambientes que necesite. Por esto, se recomienda que cree en Apicurio una API por cada ambiente que maneje y agregue un sufijo para identificarla rápidamente, a excepción del ambiente de producción que es más limpio titularlo con el nombre del sistema.

Por ejemplo:

• API
• API - DEV
• API - QA

Una vez que si API está lista para ser utilizada (ya sea para que un generador la use o un desarrollador externo la consulte), se deberá generar un liga fija para consultar su API.

Haga clic en el botón de tres puntos verticales para ver las opciones sobre la API y elija "Compartir docs" (Share Docs).

A continuación presione el botón de "Habilitar Compartir" (Click here to enable sharing)

Una vez que se habilita la opción de compartir, se genera una URL pública para el API

Para publicar el API de forma automática, se debe configurar el proyecto para que su ciclo de integración continua envíe los cambios del API al servidor de Apicurio.

Esto se puede hacer tanto en DroneCI como en la Gitlab CI, en cualquiera de los casos, es necesario agregar los siguientes secrets o variables (para DroneCI o Gitlab CI respectivamente):

En el archivo .drone.yml se deberá agregar un paso como el siguiente:

kind: pipeline
type: docker
name: default

steps:
  - name: apicurio api publish
    image: registry.crip.conacyt.mx/library/post-oas
    commands:
      - post-oas src/main/resources/swagger/api.yml
    environment:
      APICURIO_DESIGN_MASTER_ID: <ID para OAS de producción>
      APICURIO_DESIGN_DEV_ID: <ID para OAS de desarrollo>
      APICURIO_HOST:
        from_secret: apicurio_host
      APICURIO_CLIENT_SECRET:
        from_secret: apicurio_client_secret
      API_USER_NAME:
        from_secret: apicurio_user
      APICURIO_USER_PASSWORD:
        from_secret: apicurio_user_password
    when:
      branch:
        include:
          - develop
          - main
          - master
      event:
        - push

El ID de los proyectos de ApiCurio se pude sacar de la URL del proyecto. La URL del API tiene la siguiente estructura:

https://api.test.crip.conacyt.mx/apis/2

En el caso del ejemplo, el ID es 2.

En el archivo .gitlab-ci.yml deberá agregar un paso como el siguiente:

oas-publish:
  stage: deploy
  image: registry.crip.conacyt.mx/library/post-oas
  script:
    - post-oas src/main/resources/swagger/api.yml
  variables:
    APICURIO_DESIGN_MASTER_ID: <ID para OAS de producción>
    APICURIO_DESIGN_DEV_ID: <ID para OAS de desarrollo>
    API_USER_NAME: $api_user_name
    APICURIO_HOST: $apicurio_host
    APICURIO_CLIENT_SECRET: $apicurio_client_secret
    APICURIO_USER_PASSWORD: $apicurio_user_password
  only:
    refs:
      - develop
      - main
    changes:
      - src/main/resources/swagger/api.yml
  except:
    - merge_requests
    - triggers

El ID de los proyectos de ApiCurio se pude sacar de la URL del proyecto. La URL del API tiene la siguiente estructura:

https://api.test.crip.conacyt.mx/apis/2

En el caso del ejemplo, el ID es 2.

Realice push de los cambios que acaba de realizar y pruebe que, en efecto, se publica automáticamente la OAS.