Versões comparadas
Chave
- Esta linha foi adicionada.
- Esta linha foi removida.
- A formatação mudou.
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. 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 erro403
. - 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.
Â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 (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 - <TODO: Habilitar os recursos do Swagger na entidade do Diagrama de dados>e definir as permissões nas entidades do Diagrama de dados
Informações |
---|
Após configurar a classe no Diagrama de dados, é necessário gerar novamente a camada de persistência para a classe. |
Â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.
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".
Image Added
Figura 2.2 - <TODO: Habilitar os recursos do Swagger na Fonte de dados>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".
Image Added
Figura 2.3 - Definir as permissões dos Campos e Campos calculados da Fonte de dados
Âncora | ||||
---|---|---|---|---|
|
Habilitar Blocos de programação
O Os blocos de programação (servidor) podem gerar endpoints em qualquer formato, dessa forma, o desenvolvedor é livre para definir o retorno do recurso. 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).
Aviso |
---|
Ao habilitar o Swagger nas |
Propriedades do bloco de programação, todas as funções contidas no |
Blockly (classe Java) ficarão visíveis, |
assim como as configurações de segurança nos verbos HTTP. |
Image Added
Figura 2.3 4 - <TODO: Habilitar os recursos do Swagger no editor de bloco de programação>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
Nessa página
Índice |
---|