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, execute o projeto e clique no botão de atalho Abrir Navegador para exibir os links (Figura 2.5),

Figura 2.5 - Acesso a ferramenta do Swagger e a estrutura do OpenAPI

1. Visualizar documentação das APIs (Swagger): abre outra aba no navegador com a ferramenta do Swagger.
2. 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

Página do Swagger

É possível abrir a página do Swagger a partir do menu Abrir Navegador > Visualizar documentação das APIs (Swagger) (Figura 2.5) ou através do endereço "<domínio>/api/metadata/". 

A página irá exibir todos os recursos disponibilizados através das configurações do projeto e nas configurações do próprio recurso. Ficarão visíveis, como documentação, os recursos públicos e privados, porém, só será possível executar os recursos privados após informar o token de um usuário com permissões compatíveis aos endpoints do recurso.

Figura 3 - Principais elementos da página do Swagger

1. Nome do projeto.
2. Botão Autorizar: permite adicionar um token de autorização, habilitando os recursos privados. Acesse o tópico Acesso aos recursos privados para mais detalhes.
3. Campo Filtro: filtra pelos nomes dos recursos.
4. Recursos: Acordeões dos recursos, ao clicar, serão exibidos os subacordeões com seus endpoints.
5. Endpoints do recurso: acordeões com os endpoints do recurso selecionado.
6. Schemas: modelos usados nos recursos dos tipos Entidade e Fonte de dados.

Endpoints dos recursos

Cada recurso pode conter diversos acordeões com endpoints associados. O acordeão do endpoint possui toda a estrutura necessária para executá-lo em outro sistema, exibindo: endereço, parâmetros, exemplo do corpo da requisição (verbos POST e PUT) e exemplos de resposta.

Figura 3.1 - Elementos do acordeão do endpoint

1. Nome do recurso: acordeão com o nome do recurso, ao clicar, irá expandir ou recolher os acordeões com os endpoints.
2. Verbo: verbo HTTP do endpoint. Cada verbo possui uma cor, facilitando sua identificação:
   • POST: verde;
   • GET: azul;
   • DELETE: vermelho;
   • PUT: laranja.
3. endpoint: deve ser concatenado com o domínio do sistema. Ex.: "<domínio>/api/cronapi/odata/v2/app/Entidade"
4. Botão Testar: ao clicar, exibirá campos para permitir executar o endpoint na própria página do Swagger. Caso o recurso necessite de permissão, será necessário realizar a autenticação primeiro.
5. Parâmetros: campos com a lista de parâmetros definidos pelo endpoint. São exibidos o nome, tipo e formato em que é passado o parâmetro:
   • path: quando o parâmetro é passado pelo endereço. Ex.: /api/cronapi/odata/v2/app/minhaFonteDados('<parametro>')
   • query: quando o parâmetro é passado via queryString. Ex.: /api/cronapi/odata/v2/app/minhaFonteDados?parametro=valor
6. Corpo da requisição: exibido apenas nos verbos POST e PUT, esse campo exibe o modelo do objeto.
7. Respostas: exibe exemplos de respostas para alguns códigos HTTP. Exemplos que retornam listas sempre exibirá apenas um objeto.

Schemas

A área de Schemas exibirá acordeões com os modelo dos objetos usados pelos recursos Entidades e Fonte de dados. Além do nome do atributo, serão exibidos também o tipo do atributo e uma descrição, que por padrão, será o próprio nome do atributo.

Figura 3.2 - Acordeão dos modelos usados nas Entidades e Fonte de dados

Acesso aos recursos privados

Para executar os endpoints dos recursos privados na página do Swagger, é necessário informar o token de acesso de um usuário que possua um nível de autorização compatível com o endpoint a ser testado.

Ao habilitar a opção Ativar para autenticação nas Configurações do projeto (Figura 2), o recurso Autorização ficará disponível na página do Swagger, ele possui os endpoints:

• "/auth", em que permite informar o login e senha de um usuário para obter o seu token de acesso;
• "/auth/refresh", onde é possível atualizar o token após finalizar o tempo de expiração do próprio token.

Para autenticar na página do Swagger, acesse o endpoint "/auth" do recurso Autorização e clique no botão Testar (destaque 1 da figura 3.3).

Figura 3.3 - Execução do endpoint de autenticação

Os campos username e password no Corpo da requisição (1 da figura 3.4) ficarão disponíveis para inserir um usuário do sistema, informe um usuário válido e clique no botão Execute (2). No campo Response Body do código "200" em Respostas será exibido o retorno da requisição, selecione e copie apenas o conteúdo do atributo token (3). 

Figura 3.4 - Obtendo o token do usuário no retorno da requisição

Clique no botão Autorizar (destaque 1 da figura 3.5) no começo da página do Swagger para abrir o modal Autenticação disponível, informe o token obtido no campo Valor e clique no botão Autorizar do modal. Feche o modal e os recursos privados, cujo usuário informado tenha acesso, estarão disponíveis. 

Figura 3.5 - Informando o Token de acesso no modal de Autenticação

Será apresentado código "500" (Não autorizado) nas seguintes situações:

• Não informar um token;
• Não informar um token válido;
• Informar o token de um usuário que não possua autorização para executar o endpoint de um determinado recurso.

Executar testes

É possível utilizar a página do Swagger para testar todos os endpoint disponíveis