Saltar al contenido

Publica un documento OpenAPI (Swagger) para la API REST de tu aplicación en Jitterbit App Builder

Introducción

Un documento OpenAPI (Swagger) es una descripción estandarizada y legible por máquina de una API REST, definida por la Especificación OpenAPI. Desde App Builder 4.67, puedes publicar un documento OpenAPI (Swagger) que describa la API REST de tu aplicación, en formato JSON o YAML. Cualquier herramienta que admita OpenAPI, ya sea otras aplicaciones de la plataforma Harmony (como API Manager) o herramientas externas de terceros, puede recuperar este documento sin autenticación para descubrir automáticamente los puntos finales disponibles de tu aplicación, sus parámetros y el método de autenticación que cada uno requiere. Esta página describe cómo publicar este documento, dónde está disponible, qué incluye y cómo se asignan los métodos de autenticación. Al final, hay una lista de problemas conocidos y limitaciones actuales.

App Builder también puede realizar la operación inversa; es decir, consumir un documento OpenAPI externo para crear un punto final REST. Consulta Importa un documento OpenAPI (Swagger) para crear un punto final para obtener más información.

Publica un documento OpenAPI

App Builder no publica un documento OpenAPI para las APIs de tu aplicación de forma predeterminada. Antes de poder publicar uno, ya debes haber publicado la aplicación como un punto final de API REST. Para publicar un documento OpenAPI, sigue estos pasos:

  1. Ve a IDE > REST APIs.

  2. Localiza la aplicación para la que deseas publicar un documento OpenAPI y haz clic en el icono de chevron en su tarjeta. Se abre la página REST API para esa API.

    Si no ves tu aplicación en la lista, aún no la has publicado como un punto final de API REST.

  3. En el panel Service, haz clic en Edit.

  4. Marca la opción Publish Documentation. Esto le indica a App Builder que genere y publique el documento OpenAPI.

  5. Opcionalmente, proporciona un Summary y una Description.

  6. Haz clic en Save.

De forma predeterminada, App Builder incluirá todos los recursos de la API en el documento OpenAPI, a menos que selecciones recursos para excluir.

Excluye un recurso de la documentación de la API

Si deseas excluir un recurso individual de la documentación OpenAPI que se generará, esto también se configura desde la página REST API de la API:

  1. Ve a IDE > REST APIs.

  2. Localiza la aplicación para la que deseas publicar un documento OpenAPI y haz clic en el icono de chevron en su tarjeta. Se abre la página REST API para esa API.

    Si no ves tu aplicación en la lista, aún no la has publicado como un punto final de API REST.

  3. En el panel Resources, localiza el recurso que deseas excluir de la documentación y haz clic en su icono de detalles . Se abre la página REST Resource para ese recurso.

  4. En el panel Resource, haz clic en Edit.

  5. Marca la opción Exclude From Documentation. Al hacerlo, se omite ese recurso del documento generado, incluso cuando Publish Documentation está habilitado para la API REST en su conjunto.

  6. Haz clic en Save.

Detalles del documento OpenAPI

Esta sección describe los detalles del documento OpenAPI que App Builder puede publicar para las APIs REST de tu aplicación.

URL del documento

Una vez publicado, el documento OpenAPI está disponible en la misma URL base que tu API REST de la aplicación, con openapi.json u openapi.yaml añadido:

.../rest/v1/{endpoint}/openapi.json
.../rest/v1/{endpoint}/openapi.yaml

Reemplaza {endpoint} con el punto final de API REST configurado para tu aplicación (por ejemplo, northwinds).

Contenido del documento

El documento OpenAPI generado refleja la API REST expuesta por la aplicación:

  • Cada recurso publicado, incluyendo cualquier nodo secundario, se convierte en una path en el documento.

  • Las columnas y propiedades de objetos de negocio se convierten en campos en el modelo correspondiente de components/schemas, con sus tipos de datos de App Builder asignados a tipos de datos de OpenAPI.

  • Los parámetros de entrada se convierten en parámetros de ruta o consulta de OpenAPI.

  • Solo se incluyen los eventos personalizados seleccionados para exposición REST, utilizando su nombre configurado compatible con URL.

Asignación de autenticación

El documento generado declara un esquema de seguridad en components/securitySchemes para cada método de autenticación configurado en los puntos finales de la aplicación:

Método de autenticación de App Builder Esquema de seguridad OpenAPI generado
Acceso anónimo Sin requisito de seguridad en la ruta.
OAuth, concesión de credenciales de cliente Flujo OAuth2 clientCredentials.
OAuth, concesión de código de autorización Flujo OAuth2 authorizationCode.
Clave de API Esquema de seguridad de clave de API utilizando un encabezado personalizado (X-API-Key de forma predeterminada).

Problemas conocidos y limitaciones

El documento generado está sujeto a los mismos problemas conocidos y limitaciones que la API REST subyacente.