Publicar um documento OpenAPI (Swagger) para a API REST do seu aplicativo 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 aplicativo, 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, como os métodos de autenticação são mapeados e como listar todas as APIs publicadas no seu servidor App Builder. 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ê já deve ter publicado o aplicativo 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 chevron no seu bloco. 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 instrui o App Builder a 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 desejar 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 chevron no seu bloco. 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 no í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á ativado 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 fica disponível na mesma URL base que sua API REST do aplicativo, com openapi.json ou openapi.yaml adicionado:

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

Substitua {endpoint} pelo endpoint da REST API configurado para sua aplicação (por exemplo, northwinds).

Conteúdo do documento

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

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

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

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

• (Desde o App Builder 4.68.) Cada campo do nó raiz de um recurso torna-se um parâmetro de consulta opcional, documentando como filtrar resultados por esse campo usando uma comparação simples de igualdade.

• Apenas eventos personalizados selecionados para exposição REST são incluídos, utilizando seu nome configurado compatível com 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:

Listar APIs publicadas em seu servidor App Builder

Desde o App Builder 4.68, é possível descobrir cada aplicação no servidor App Builder com um documento OpenAPI publicado recuperando a seguinte URL:

.../rest/v1/services.json

Substitua a URL base pela URL do seu servidor App Builder. Este endpoint não requer autenticação.

A resposta é um array JSON com uma entrada por aplicação que possui um documento OpenAPI publicado. Uma aplicação sem um documento publicado não é incluída:

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

Problemas conhecidos e limitações

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