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 o recurso, é necessário acessar o acordeão Swagger/OpenAPI na aba Configurações do Projeto da janela de Configurações do projeto.

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>