Publicar um documento OpenAPI (Swagger) para a API REST do seu app no Jitterbit App Builder

Introdução

Um documento OpenAPI (Swagger) é uma descrição padronizada e legível por máquina de uma API REST, definida pela Especificação OpenAPI. Desde o App Builder 4.67, você pode publicar um documento OpenAPI (Swagger) que descreve a API REST do seu app, em formato JSON ou YAML. Qualquer ferramenta que suporte OpenAPI, seja outros aplicativos da plataforma Harmony (como o API Manager) ou ferramentas externas de terceiros, pode recuperar este documento sem autenticação para descobrir automaticamente os endpoints disponíveis do seu aplicativo, seus parâmetros e o método de autenticação que cada um requer. Esta página descreve como publicar este documento, onde ele está disponível, o que ele inclui e como os métodos de autenticação são mapeados. No final, há uma lista de problemas conhecidos e limitações atuais.

O App Builder também pode fazer a operação inversa; ou seja, consumir um documento OpenAPI externo para criar um endpoint REST. Consulte Importar um documento OpenAPI (Swagger) para criar um endpoint para saber mais.

Publicar um documento OpenAPI

O App Builder não publica um documento OpenAPI para as APIs do seu aplicativo por padrão. Antes de publicar um, você deve ter publicado o app como um endpoint de API REST. Para publicar um documento OpenAPI, siga estas etapas:

1. Acesse IDE > REST APIs.

2. Localize o aplicativo para o qual deseja publicar um documento OpenAPI e clique no ícone de chevron em seu tile. A página REST API dessa API é aberta.

   Se você não vir seu aplicativo listado, ainda não o publicou como um endpoint de API REST.

3. No painel Service, clique em Edit.

4. Marque a opção Publish Documentation. Isso informa ao App Builder para gerar e publicar o documento OpenAPI.

5. Opcionalmente, forneça um Summary e uma Description.

6. Clique em Save.

Por padrão, o App Builder incluirá todos os recursos da API no documento OpenAPI, a menos que você selecione recursos para excluir.

Excluir um recurso da documentação da API

Se você deseja excluir um recurso individual da documentação OpenAPI que será gerada, isso também é configurado na página REST API da API:

1. Acesse IDE > REST APIs.

2. Localize o aplicativo para o qual deseja publicar um documento OpenAPI e clique no ícone de chevron em seu tile. A página REST API dessa API é aberta.

   Se você não vir seu aplicativo listado, ainda não o publicou como um endpoint de API REST.

3. No painel Resources, localize o recurso que deseja excluir da documentação e clique em seu ícone de detalhes. A página REST Resource desse recurso é aberta.

4. No painel Resource, clique em Edit.

5. Marque a opção Exclude From Documentation. Fazer isso omite esse recurso do documento gerado, mesmo quando Publish Documentation está habilitado para a API REST como um todo.

6. Clique em Save.

Detalhes do documento OpenAPI

Esta seção descreve os detalhes do documento OpenAPI que o App Builder pode publicar para as APIs REST do seu aplicativo.

URL do documento

Após publicado, o documento OpenAPI está disponível na mesma URL base da API REST do seu app, com openapi.json ou openapi.yaml adicionado:

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

Substitua {endpoint} pelo endpoint de API REST configurado para seu aplicativo (por exemplo, northwinds).

Conteúdo do documento

O documento OpenAPI gerado reflete a API REST exposta pela aplicação:

• Cada recurso publicado, incluindo qualquer nó filho, se torna um path no documento.

• As colunas e propriedades de objetos de negócio se tornam campos no modelo components/schemas correspondente, com seus tipos de dados do App Builder mapeados para tipos de dados OpenAPI.

• Os parâmetros de entrada se tornam parâmetros de caminho ou consulta OpenAPI.

• Apenas eventos personalizados selecionados para exposição REST são incluídos, usando seu nome configurado amigável para URL.

Mapeamento de autenticação

O documento gerado declara um esquema de segurança em components/securitySchemes para cada método de autenticação configurado nos endpoints da aplicação:

Problemas conhecidos e limitações

O documento gerado está sujeito aos mesmos problemas conhecidos e limitações da API REST subjacente.