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 (destaque 1 da figura 2) na aba Configurações do Projeto da janela de Configurações do projeto. Além disso, cada recurso (entidade, fonte de dados ou bloco de programação) necessita ser configurado individualmente, habilitando o recurso nas suas configurações e definindo a restrição de execução de cada verbo HTTP.

Figura 2 - Opções nas configurações do Swagger/OpenAPI

• 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.

Para habilitar o recurso, acesse a janela de Manipulação da classe e selecione o campo Swagger/Open API (destaque 2 da figura 2.1) ou selecione a classe (destaque 1) e marque a opção Swagger nos campos da Propriedades e Eventos do menu lateral (destaque 3).

É possível definir as Permissões nos verbos HTTP do recurso e também sobre cada atributo da classe:

• Para a entidade, selecione a classe (destaque 1) e, em seguida, acesse a propriedade Security (destaque 4 da figura 2.1) nos campos da Propriedades e Eventos do menu lateral para abrir a janela de configuração dos verbos. Através dessa janela é possível definir. por exemplo, que o verbo Delete (Permitir Deletar) será executado apenas por usuários "Administradores".
• Para o atributo, acesse a janela de manipulação da classe e clique sobre o botão Permissão (destaque 5 da figura 2.1) de um dos atributos. Através dessa janela é possível definir. por exemplo, que o atributo selecionado será visível (Permitir Obter, verbo Get) para usuários "Administradores".
  Obs.: A janela de Permissão do atributo possui um campo a mais, o Permitir Filtrar, que não foi apresentado na figura 2.1.

Figura 2.1 - Habilitar os recursos do Swagger e definir as permissões nas entidades 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.

Para habilitar o recurso, acesse a janela de configurações da Fonte de dados e marque a opção Swagger/Open API (destaque 1 da figura 2.2).

É possível definir as Permissões nos verbos HTTP do recurso e também sobre cada campo da Fonte de dados:

• Para o recurso, selecione a aba Ações e, em seguida, clique no botão de Permissão do verbo HTTP (destaque 2 da figura 2.2) para abrir a janela de Permissão de Segurança, por padrão, todos os verbos vêm configurado como "Autenticado". Através dessa janela é possível definir. por exemplo, que o verbo Delete (Para Remover) será executado apenas por usuários "Administradores". 

Figura 2.2 - Habilitar os recursos do Swagger e definir as permissões da Fonte de dados

• Para o atributo, selecione a aba Campos ou Campos calculados e, em seguida, clique no botão de Permissão do verbo HTTP (destaque 1 da figura 2.3) de um dos campos para abrir a janela de Permissão de Segurança, por padrão, todos os verbos vêm configurado como "Autenticado". Através dessa janela é possível definir. por exemplo, que o campo selecionado será visível (Para Obter, verbo Get) para usuários "Administradores".

Figura 2.3 - Definir as permissões dos Campos e Campos calculados da Fonte de dados

Habilitar Blocos de programação

Os blocos de programação (servidor) podem gerar endpoints que retornam qualquer formato. Veja mais detalhes no tópico "Via bloco de programação" da documentação Disponibilizando Web Service REST.

Para habilitar o recurso no Swagger, acesse a janela Propriedades do bloco de programação (destaque 1 da figura 2.4) e marque a opção Expor Swagger (destaque 2).

É possível definir as permissões dos verbos HTTP a partir da propriedade Segurança (destaque 3).

Figura 2.4 - Habilitar os recursos do Swagger e definir as permissões do 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

Swagger