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.

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 - 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 o recurso no 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 o recurso no 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 o recurso no 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 (ícone globo) para exibir os links (Figura 2.5),

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

1. Swagger UI: abre outra aba no navegador com a página do Swagger.
2. Arquivo 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 (ícone globo) > Swagger UI (destaque 1 da 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 privado.

Figura 3 - Principais elementos da página do Swagger

1. Nome do projeto.
2. Botão Autorizar: permite adicionar um token de autorização para habilitar os recursos privados. Acesse o tópico Acesso aos recursos privados para mais detalhes.
3. Campo Filtro: filtra pelos nomes dos recursos (entidades, fonte de dados e blocos de programação).
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, o acordeão do endpoint sairá do modo leitura para o modo de teste, tornando seus campos editáveis e permitindo realizar uma requisição. Acesse o tópico Executar testes para mais detalhes.
5. Parâmetros: campos com a lista de parâmetros definidos pelo endpoint. No acordeão do verbo GET dos recursos OData serão exibidos os próprios parâmetros do recurso e os parâmetros de query string do OData, acesse o tópico "Parâmetros de Query String" na documentação Fonte de Dados para mais detalhes.
   São exibidos o nome, o tipo e formato em que é passado o parâmetro:
   • path, quando o parâmetro é passado pela rota do 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 schema do objeto a ser enviado.
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 modelos 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 - Endpoint de autenticação ainda em modo leitura

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 em Respostas, caso o código tenha retornado o valor "200", 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) ao executar um endpoint privado 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, desde que possua autorização para isso.

O acordeão do endpoint poderá mudar o seu formato a depender do modo de acesso, alternando em 3 situações: Leitura, Teste e Retorno.

• Leitura: antes de clicar no botão Testar (4 da figura 3.1).
  • As áreas Parâmetros (2 da figura 3.6) e Corpo da requisição (nos verbos POST e PUT) (3 da figura 3.6) estarão disponíveis apenas como leitura, servindo de documentação do recurso.
  • A área de Respostas só exibirá os exemplos, os campos de retorno do teste estarão ocultos (4 da figura 3.6).
• Teste: após clicar no botão Testar (4 da figura 3.1).
  • O botão Testar alterna para Cancelar (destaque 1 da figura 3.6) e tem a função de retornar ao modo leitura.
  • As áreas Parâmetros (2 da figura 3.6) e Corpo da requisição (nos verbos POST e PUT) (3 da figura 3.6) ficarão editáveis, permitindo inserir os dados que serão enviados na requisição.
  • O botão Execute ficará disponível no final da área de Parâmetros nos verbos GET e DELETE ou no final da área Corpo da requisição nos verbos POST e PUT.
  • A área de Respostas só exibirá os exemplos, os campos de retorno do teste estarão ocultos (4 da figura 3.6).
• Retorno: após enviar a requisição através do botão Execute.
  • Nos verbos POST e PUT será exibido, ao lado do botão Cancelar (destaque 1 da figura 3.6), o botão Reiniciar, que irá retornar as alterações do campo Corpo da requisição (3 da figura 3.6) para o exemplo padrão (figura 3.7).
  • Ao lado do botão Execute será exibido o botão Clear, com a função de ocultar os campos de resposta da requisição (figura 3.7).
  • A área de Respostas exibirá os campos com os dados da requisição e seu retorno (destaques 1, 2 e 3 da figura 3.7).

Figura 3.6 - Endpoint em modo de Teste

Após executar a requisição, a área de Respostas exibirá os campos informando o que foi enviado ao servidor e sua resposta (Figura 3.7).

Figura 3.7 - Campos exibidos após a resposta do servidor

1. Curl: dados da requisição em formato curl.
2. Requisição URL: endereço a ser requisitado.
3. Server response: exibe o código HTTP com a resposta do servidor e 2 campos com os detalhes da resposta,
   • Response body: corpo da requisição de resposta,
   • Response headers: cabeçalho da requisição de resposta.