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.
Image Added
Figura 1 - <TODO: visão Visão geral da página do Swagger>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.
Âncora | ||||
---|---|---|---|---|
|
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 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>Habilitar o recurso no Swagger 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>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".
Image Added
Figura 2.3 - Definir as permissões dos Campos e Campos calculados da Fonte de dados
Informações |
---|
Apesar dos Campos calculados não serem persistidos, caso a Fonte de dados possua esse tipo de atributo, ele será visível na lista de schemas do Swagger. Veja mais detalhes no tópico "Campos calculados" na documentação 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> 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, diretamente nas configurações do próprio recurso, acesse o execute o projeto e clique no botão de atalho Abrir Navegador (com o projeto em execução) e selecione as opções: (ícone globo) para exibir os links (Figura 2.5),
Image Added
Figura 2.4 5 - <TODO: Acesso a ferramenta e esquema>
Visualizar documentação das APIs (Swagger)do Swagger e a estrutura do OpenAPI
- Swagger UI: abre outra aba no navegador com a
- página do Swagger.
- 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/
<domínio>/api/metadata/configuration
Swagger
configuration
Âncora paginaSwagger paginaSwagger
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.
Image Added
Figura 3 - Principais elementos da página do Swagger
- Nome do projeto.
- 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.
- Campo Filtro: filtra pelos nomes dos recursos (entidades, fonte de dados e blocos de programação).
- Recursos: Acordeões dos recursos, ao clicar, serão exibidos os subacordeões com seus endpoints.
- Endpoints do recurso: acordeões com os endpoints do recurso selecionado.
- 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.
Informações |
---|
Por padrão, os recursos baseados em OData no Cronapp (Entidades e Fontes de dados) retornam sempre no formato XML, porém na página do Swagger o retorno dos mesmos recursos serão exibidos sempre em JSON. Ao consumir esses recursos em outros locais, é possível definir o formato desejado informando a queryString " |
Image Added
Figura 3.1 - Elementos do acordeão do endpoint
- Nome do recurso: acordeão com o nome do recurso, ao clicar, irá expandir ou recolher os acordeões com os endpoints.
- Verbo: verbo HTTP do endpoint. Cada verbo possui uma cor, facilitando sua identificação:
- POST: verde;
- GET: azul;
- DELETE: vermelho;
- PUT: laranja.
- Endpoint: deve ser concatenado com o domínio do sistema. Ex.: "
<domínio>/api/cronapi/odata/v2/app/Entidade
" - 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.
- 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
- path, quando o parâmetro é passado pela rota do endereço. Ex.:
- Corpo da requisição: exibido apenas nos verbos POST e PUT, esse campo exibe o schema do objeto a ser enviado.
- 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.
Informações |
---|
Atributos do tipo Campos calculados (campos não persistidos) da fonte de dados serão exibidos como um atributo comum do modelo. |
Image Added
Figura 3.2 - Acordeão dos modelos usados nas Entidades e Fonte de dados
Âncora | ||||
---|---|---|---|---|
|
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).
Informações |
---|
É importante destacar que em projetos do tipo Microsserviços, que não possuem interfaces clientes e de autenticação, para autorizar um serviço é preciso fazer a integração com outra aplicação que gerencie a autenticação, a fim de obter o token do usuário e executar a ação que informa o token do usuário. Para mais detalhes, consulte o tutorial Projeto de Microsserviços com autenticação. |
Image Added
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).
Image Added
Figura 3.4 - Obtendo o token do usuário no retorno da requisição
Âncora | ||||
---|---|---|---|---|
|
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.
Image Added
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.
Informações |
---|
Será necessário realizar esse procedimento de autenticação sempre que atualizar a página do Swagger. |
Âncora | ||||
---|---|---|---|---|
|
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).
Image Added
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).
Image Added
Figura 3.7 - Campos exibidos após a resposta do servidor
- Curl: dados da requisição em formato curl.
- Requisição URL: endereço a ser requisitado.
- 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.