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
- Projeto servidor criado. Caso haja dúvidas de como criar esse tipo de projeto acesse o link ( Criar projeto ).
- Para executar os recursos privados, o tipo de autenticação do projeto deve ser: Token, SSO (Oauth2) ou Sessão.
- É 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 (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 nas suas configurações e definindo a restrição de execução de cada verbo HTTP.
Figura 2 - <TODO: Habilitar os recursos do Swagger>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 erro403. - Ativar para autenticação: exibe os endpoints de autorização (
/authe/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.
| Âncora | ||||
|---|---|---|---|---|
|
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 (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 - <TODO: Habilitar os recursos do Swagger na entidade do Diagrama de dados>
| Âncora | ||||
|---|---|---|---|---|
|
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>
| Âncora | ||||
|---|---|---|---|---|
|
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
Swagger
Nessa página
| Índice |
|---|