O Swagger ui é uma interface de documentação e teste dos recursos RESTfull de um sistema, dessa forma, qualquer usuário com acesso poderá obter os endpoints disponibilizados, entender como configurá-los e ver o formato de seus retornos. A ferramenta do Swagger é baseada na especificação do OpenAPI (v. 3.0.3) e sua estrutura pode ser exportada para ser utilizada por outras ferramentas que também suportam o OpenAPI em sua versão 3.0.3.

O conteúdo apresentado na página do Swagger é gerado automaticamente pelo Cronapp, o usuário necessitará apenas configurar quais recursos ficarão visíveis e definir o nível de restrição para o uso. É possível habilitar os recursos gerados por entidades no Diagrama de dados, Fontes de dados e Blocos de programação (servidor), além disso, é possível definir o nível de segurança (permissionável) para cada verbo HTTP dos recursos.

Figura 1 - <TODO: visão geral da página do Swagger>

Pré-requisitos

1. Projeto servidor criado. Caso haja dúvidas de como criar esse tipo de projeto acesse o link ( Criar projeto ).
2. Para executar os recursos privados, o tipo de autenticação do projeto deve ser: Token, SSO (Oauth2) ou Sessão.
3. É importante que o usuário tenha algum conhecimento sobre a tecnologia REST para entender e utilizar os recursos apresentados na página do Swagger.

Como configurar

Para habilitar a ferramenta, é necessário acessar o acordeão Swagger/OpenAPI na aba Configurações do Projeto da janela de Configurações do projeto (Figura 2). Além disso, cada recurso (entidade, fonte de dados ou bloco de programação) necessita ser configurado individualmente, habilitando o recurso em si e configurando a restrição de execução de cada verbo.

Figura 2 - <TODO: Habilitar os recursos do Swagger>

• Ativar documentação de API's REST: habilita o recurso do Swagger através do endereço "<domínio>/api/metadata/". Caso essa opção esteja desabilitada, será exibido um erro 403.
• Ativar para autenticação: exibe os endpoints de autorização (/auth e /auth/refresh) na tela do Swagger, permitindo testar os recursos privados. 
• Ativar para entidades: exibe os recursos REST habilitados nas classes do Diagrama de dados.
• Ativar para fontes de dados: exibe os recursos REST habilitados nas Fontes de dados.
• Ativar para blocos: exibe os recursos REST habilitados nas configurações dos Blocos de programação.

Habilitar entidades

As classes criadas no Diagrama de dados podem gerar endpoints OData e são configuráveis a partir do próprio diagrama de dados.

Figura 2.1 - <TODO: Habilitar os recursos do Swagger na entidade do Diagrama de dados>

Habilitar Fonte de dados

Os datasources do Cronapp geram endpoints OData e são configuráveis a partir da própria janela da Fonte de dados.

Figura 2.2 - <TODO: Habilitar os recursos do Swagger na Fonte de dados>

Habilitar Blocos de programação

O blocos de programação podem gerar endpoints em qualquer formato, dessa forma, o desenvolvedor é livre para definir o retorno do recurso. Ao habilitar o Swagger nas configurações do editor Blockly, todas as funções contidas no arquivo ficarão visíveis, as restrições definidas para os verbos HTTP também serão herdadas por todas as funções.

Figura 2.3 - <TODO: Habilitar os recursos do Swagger no editor de bloco de programação>

Acesso ao Swagger e a estrutura do OpenAPI

Após habilitar o Swagger nas Configurações do projeto e em cada recurso que deseja expor, diretamente nas configurações do próprio recurso, acesse o botão de atalho Abrir Navegador (com o projeto em execução) e selecione as opções:

Figura 2.4 - <TODO: Acesso a ferramenta e esquema>

• Visualizar documentação das APIs (Swagger): abre outra aba no navegador com a ferramenta do Swagger. Acessível também através do seu endereço: <domínio>/api/metadata/
• Visualizar arquivo de configuração (OpenAPI): abre outra aba no navegador com o esquema do OpenAPI. Acessível também através do seu endereço: <domínio>/api/metadata/configuration