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áquinas de una API REST, definida por la Especificación OpenAPI. A partir de 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 sea compatible con OpenAPI, ya sea otras aplicaciones de la plataforma Harmony (como API Manager) u 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, cómo se asignan los métodos de autenticación y cómo listar cada API publicada en tu servidor de App Builder. Al final, hay una lista de los 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 cual 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 listada, 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 cual 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 listada, 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 de conexión de la 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, incluidos todos los nodos secundarios, 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.

• (Desde App Builder 4.68.) Cada campo del nodo raíz de un recurso se convierte en un parámetro de consulta opcional, documentando cómo filtrar resultados por ese campo usando una comparación de igualdad simple.

• Solo se incluyen los eventos personalizados seleccionados para exposición REST, usando 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 de conexión de la aplicación:

Enumera las API publicadas en tu servidor de App Builder

Desde App Builder 4.68, puedes descubrir todas las aplicaciones en tu servidor de App Builder que tengan un documento OpenAPI publicado recuperando la siguiente URL:

.../rest/v1/services.json

Reemplaza la URL base con la URL de tu servidor de App Builder. Este punto de conexión no requiere autenticación.

La respuesta es un array JSON con una entrada por cada aplicación que tenga un documento OpenAPI publicado. Una aplicación sin un documento publicado no se incluye:

[
  {
    "name": "Northwinds",
    "endpoint": "northwinds",
    "url": "https://example.com/rest/v1/northwinds",
    "openApiUrl": "https://example.com/rest/v1/northwinds/openapi.json"
  }
]

Problemas conocidos y limitaciones

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