Página del Administrador del Portal en Jitterbit API Manager

Introducción

La página del Administrador del Portal permite generar documentación OpenAPI para todas las APIs personalizadas y proxy en un entorno a la vez. La documentación resultante se muestra en la página del Portal de API, donde se puede interactuar con ella probando las APIs. Para generar documentación para una API individual en su lugar, utiliza la pestaña Documentación en la página de APIs. Esta página describe la interfaz de usuario de la página del Administrador del Portal dentro del API Manager.

Limitaciones

La página del Administrador del Portal tiene estas limitaciones:

• La generación de documentación OpenAPI para APIs OData no es compatible al usar Regenerar Docs. Para generar documentación para una API OData individual, utiliza la pestaña Documentación en la página de APIs.
• La generación de documentación OpenAPI para servicios de API que utilizan un método de solicitud personalizado no es compatible debido a una limitación de la especificación OpenAPI. Las APIs que incluyen solo servicios de API de método personalizado se muestran con un nombre de etiqueta de API solamente.
• Solo se puede crear una única página de Portal de API para cada entorno en una organización Harmony.

Acceder a la página del Administrador del Portal

Para acceder a la página del Administrador del Portal, utiliza el menú del portal Harmony para seleccionar API Manager > Administrador del Portal.

Editor OpenAPI

El Editor de OpenAPI incluye los siguientes controles:

• Entorno: Utiliza el menú para seleccionar el entorno donde se generará la documentación de OpenAPI y luego se mostrará en la página del Portal API de una organización.

  Nota

  Solo se puede crear una única página de Portal API para cada entorno en una organización de Harmony.

• Carga de logo: Puedes personalizar la página del Portal API arrastrando y soltando una imagen en la zona de carga o seleccionando una manualmente. Tu carga se publica automáticamente en la página del Portal API sin necesidad de hacer clic en Regenerar Docs o Guardar y Publicar.

• Regenerar Docs: Haz clic para regenerar y publicar la documentación de OpenAPI 2.0 en la página del Portal API para todas las APIs personalizadas y proxy en el entorno seleccionado. Las APIs OData están excluidas. Si has publicado una nueva API personalizada o proxy y deseas regenerar automáticamente la documentación para incluir cualquier nueva API, debes usar esta opción.

  Cualquier personalización que hayas guardado previamente en la documentación se preserva y se reaplica automáticamente cuando sea posible. Si una personalización entra en conflicto con la documentación regenerada, debes resolver el conflicto antes de poder guardar y publicar la documentación. Para más información, consulta Resolver conflictos de personalización.

• Guardar y Publicar: Haz clic para guardar y publicar la documentación de la API en la página del Portal API. Si has aplicado alguna personalización a la documentación de la API generada automáticamente, debes usar esta opción para publicar la documentación en la página del Portal API. Este botón está deshabilitado hasta que se resuelvan los conflictos de personalización.

• Editor: Cuando agregas definiciones de OpenAPI en el editor, se renderizan como documentación interactiva de Swagger UI en la Vista Previa del Portal. Puedes editar las definiciones de OpenAPI directamente dentro del editor. Estos son ejemplos de personalizaciones para la documentación de la API:

  • Rellena los metadatos sobre la API, incluyendo Campos Fijos como title, description, termsOfService, contact, license, y version.

  • Sobrescribe manualmente la documentación utilizando la Especificación OpenAPI 3.0.

  Después de realizar ediciones en la documentación de la API, haz clic en Guardar y Publicar para guardar y publicar la documentación en la página del Portal de API.

Resolve customization conflicts

Cuando haces clic en Regenerar Docs, cualquier personalización que hayas guardado previamente se compara con la nueva documentación OpenAPI generada para ese entorno.

• Sin conflictos: Si cada personalización se puede reaplicar sin conflictos, se reaplican automáticamente, y un mensaje de confirmación informa cuántas personalizaciones se reaplicaron.

• Conflictos: Si una personalización entra en conflicto con la documentación regenerada, por ejemplo, cuando el valor subyacente de un campo personalizado ha cambiado, aparece un mensaje de Personalizaciones detectadas junto con un conteo de personalizaciones pendientes. Regenerar Docs y Guardar y Publicar están deshabilitados hasta que se resuelva cada conflicto.

  

  Cada conflicto se muestra directamente en el editor entre los marcadores <<<<<<< System generated y >>>>>>> Current customization, mostrando el contenido recién generado sobre el divisor y tu personalización existente debajo de él. Para cada conflicto, haz lo siguiente:

  • Aplicar personalización: Haz clic para mantener tu personalización existente y descartar el contenido recién generado.

  • Ignorar personalización: Haz clic para descartar tu personalización existente y mantener el contenido recién generado.

  • Edita el contenido directamente en el editor para combinar o reescribir los valores en conflicto según sea necesario.

Para descartar todas las personalizaciones pendientes de una vez y mantener solo el contenido recién generado, haz clic en Ignorar todas las personalizaciones.

Un conteo en tiempo real de las personalizaciones Aplicadas, Ignoradas y Pendientes se muestra sobre el editor mientras existan conflictos. Después de resolver cada conflicto y cuando Pendientes llegue a 0, haz clic en Guardar y Publicar para publicar la documentación resuelta en la página del Portal API.

Vista previa del portal

Puedes ver las definiciones de la API como documentación interactiva de Swagger UI en la Vista previa del portal.

• Organización: La organización Harmony que se está accediendo actualmente.

• Buscar: Ingresa un nombre de API, nombre de servicio o método para filtrar las APIs disponibles que coincidan con la consulta.

• URL base: La URL base para el servicio de API. Haz clic en el ícono de copiar para copiar la URL base en tu portapapeles.

• APIs disponibles: Agrupa tus servicios de API por la raíz del servicio, por ejemplo, book o loan. Haz clic en las flechas para expandir o colapsar las APIs en ese grupo. Usa Expandir/Colapsar todo para mostrar u ocultar la lista de APIs.

Probar APIs

Cuando seleccionas un endpoint de API, su documentación interactiva de Swagger UI aparece en el lado derecho de la página. Puedes usar el Swagger interactivo para probar los servicios de API.

• Autorizar: Si alguna de las APIs dentro del entorno seleccionado requiere una autorización establecida por un perfil de seguridad asignado, se muestra un botón de Autorizar. Cuando haces clic en Autorizar, se muestra un diálogo con las autorizaciones disponibles. Completa la entrada según sea necesario para probar las APIs con los métodos de autorización proporcionados.

  

  El ícono de autorización indica si el servicio API requiere autorización:

  • : No se requiere autorización.
  • : Se requiere autorización.

• Pruébalo: Haz clic para probar la API. Se expande una solicitud API configurable:

  

  • Cancelar: Haz clic para colapsar la solicitud API configurable.

  • Ejecutar: Después de configurar los campos de la solicitud, haz clic en este botón para generar el Curl y la URL de solicitud que se utilizarán para la prueba.

    

  • Curl: La solicitud cURL para los valores ingresados en los campos de la solicitud API. Haz clic en el ícono para copiar el cURL en tu portapapeles.

  • URL de solicitud: La URL de solicitud para los valores ingresados en los campos de la solicitud.

  • Limpiar: Haz clic para limpiar los valores ingresados en los campos de la solicitud API.

Cada servicio API muestra posibles respuestas API que están incluidas en la documentación de la API:

• Respuesta del servidor: Muestra cualquier respuesta del servidor documentada.

• Respuestas: Muestra los códigos de estado HTTP documentados y sus descripciones.

Solución de problemas

Para problemas relacionados, consulta lo siguiente en la guía de solución de problemas del API Manager:

• El portal API no refleja los cambios del proyecto

• Eliminar una API no actualiza la documentación del portal API