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 APIs personalizadas y proxy. La documentación resultante se muestra en la página del Portal, donde puedes interactuar con ella probando 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 las siguientes limitaciones:

• No se admite la generación de documentación OpenAPI para servicios OData.
• No se admite la generación de documentación OpenAPI para servicios API que utilizan un método de solicitud personalizado debido a una limitación de la especificación OpenAPI. Las APIs que incluyen solo servicios API de método personalizado se muestran con un nombre de etiqueta de API únicamente.
• Solo se puede crear una única página de Portal 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.

Encabezado de la página del Administrador del Portal

La página del Administrador del Portal también se llama Administrar Portal de Desarrolladores, ya que es la página donde gestionas lo que aparece en la página del Portal (también llamada Administrar Portal de Desarrolladores).

Estas opciones aparecen en la parte superior de la página del Administrador del Portal:

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

  Para actualizar la lista de entornos, haz clic en el ícono de actualización .

  Nota

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

• Ver Documentación de la API: Haz clic para ir a la página del Portal, donde se muestra la documentación interactiva de la API generada.

• Regenerar Documentos y Publicar: Haz clic para sobrescribir y publicar la documentación OpenAPI 2.0 en la página del Portal para todas las APIs personalizadas y proxy en el entorno seleccionado. Los servicios OData están excluidos. 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.

  Advertencia

  Usar esta opción sobrescribe la documentación de la API existente, incluidas cualquier personalización. Antes de usar esta opción, se recomienda hacer una copia manual de la documentación de la API existente copiándola en un editor de texto externo. Después de regenerar la documentación, aplica manualmente cualquier personalización pegándola en el editor de documentación de la API según sea apropiado.

• Guardar y Publicar: Haz clic para guardar y publicar la documentación de la API en la página del Portal. 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.

Personalizar la página del Portal

La página del Administrador del Portal te permite personalizar la página del Portal con una imagen como un logotipo de la empresa, o con ediciones a la documentación de la API generada automáticamente:

• Explorar Archivos Locales: Haz clic para seleccionar una imagen que cumpla con los requisitos listados:

  

  La imagen subida se publica automáticamente en la página del Portal sin necesidad de hacer clic en Regenerar Documentos y Publicar o Guardar y Publicar.

  Para eliminar una imagen después de cargarla, haz clic en Eliminar imagen:

  

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

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

Editar la documentación de la API

La documentación interactiva que sigue la Especificación OpenAPI 2.0 se genera automáticamente para todas las APIs personalizadas y proxy en el entorno seleccionado.

Las definiciones de OpenAPI se muestran en el editor en el lado izquierdo de la página y se renderizan como documentación interactiva de Swagger UI en el lado derecho de la página.

Puedes editar las definiciones de OpenAPI directamente dentro del editor en el lado izquierdo de la página. Estos son ejemplos de personalizaciones para la documentación de la API:

• Completar metadatos sobre la API, incluyendo Campos fijos como title, description, termsOfService, contact, license y version.

• Sobrescribir 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.

Para regenerar y publicar la documentación después de publicar una nueva API, utiliza el botón Regenerar documentos y publicar.

Probar APIs

La documentación de la API generada a partir de las definiciones de OpenAPI mostradas en el editor en el lado izquierdo de la página, se presenta como documentación interactiva de Swagger UI en el lado derecho de la página. Puedes usar el swagger interactivo para probar los servicios de la API:

• Esquemas: Usa el menú desplegable para seleccionar entre los esquemas disponibles soportados por las definiciones de OpenAPI.

• 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. Una vez clicado, 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.

  Al hacer 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:

  

Servicios de API

Cada servicio de API se lista con su método:

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

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

Haz clic en la fila del punto final para ver información sobre sus parámetros y respuestas – descrito a continuación.

Pruébalo

En un servicio de API expandido, haz clic en el botón Pruébalo para probar la API. Se expande una solicitud de API configurable:

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

• Ejecutar: Una vez que se configuren los campos de solicitud, haz clic para generar el Curl y la URL de solicitud que se utilizarán para las pruebas:

  

  • Curl: La solicitud cURL para los valores ingresados en los campos de solicitud de 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 solicitud.

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

Las posibles respuestas de la API – las incluidas en la documentación de la API – se muestran para cada servicio de API:

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

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