Visualizar documentação

Documentação do Swagger

Síntese

e consumo de API's

O objetivo deste documento é de orientar o usuário quanto à configuração do ambiente para visualizar documentação do Swagger e permitir testes nas APIs existentes. Através dos tópicos abaixos, será exemplificado

Vamos exemplificar como configurar o ambiente corretamente para utilização dos serviços , e como é realizada realizar a segurança e autenticação através das APIs, além de exemplos de códigos utilizando os serviços disponíveis.

Expandir

title	Ajustando o ambiente	Configuração do ambiente

Pré-Requisitos: Portal RM instalado e configurado com ServiceAlias desejado (tag do arquivo Web.Config que deve conter o alias da base de dados RM que será comunicada pelo serviço).

Arquivo Web.Config

No diretório "X

Ao tentar acessar o link direto do Swagger, pode ocorrer os dois erros registrados nas imagens abaixo:

Image Removed

Dentro do servidor, abra o diretório "C:\totvs\CorporeRM\FrameHTML\bin", localize o arquivo RM.WebAPI.xml no diretório, e altere o nome para RM.WebAPI.Documentation.xml.

No mesmo diretório, localize também o arquivo RM.Fop.WebApi.dll e apague-o da pasta.

Expandir

title	Visualizando a Documentação

de configurações "Web.Config". Certifique-se que a tag "owin:AutomaticAppStartup " está com o valor "true":

Bloco de código

language	xml

<add key="owin:AutomaticAppStartup" value="true" />

Todos os serviços disponíveis no RM são agrupados e listados nessa ferramenta, que visa auxiliar na manutenção e documentação de APIs REST.

Para acessar o Swagger, é necessário acessar o link no seguinte formato : "http://<servidor>:<portaFrameHTML>/swagger/ui/index"

(Exemplo: http://localhost:8080/swagger/ui/index).

Aviso

title	URL Novo Portal

A partir da versão 12.1.28 do RM houve uma alteração na URL do novo portal, para mais detalhes acessar o TDN.

Com isso a URL do Swagger e das APIs do produto e customizações serão alteradas também.

Para verificar a porta, acesse, através do IIS, o Website "FrameHTML", que é gerado automaticamente quando realizada a instalação do Portal RM:

Image Modified

Após isso, basta clicar Clique com o botão direito do mouse no Website "FrameHTML" e clicar , em seguida, clique na opção "Editar ligações...". Conforme imagem abaixo, a porta seria a 8080, e o link ficaria da seguinte forma "http://localhost:8080/swagger/ui/index".

Image Modified

Ao tentar acessar o link direto do Swagger, podem ocorrer erros conforme imagens abaixo:

Image Added

Para ajustá-los, é necessário realizar os seguintes procedimentos:

Para o erro da primeira imagem:
- Dentro do servidor, abra o diretório "X:\totvs\CorporeRM\FrameHTML\bin", localize o arquivo RM.WebAPI.xml e altere o nome para RM.WebAPI.Documentation.xml.
Para o erro da segunda imagem:
- No mesmo diretório, localize também o arquivo RM.Fop.WebApi.dll e apague-o da pasta.

Expandir

title	Swagger - Visualizando a Documentação

Todos os serviços disponíveis no RM são agrupados e listados nesta ferramenta, que visa auxiliar na manutenção e documentação de APIs REST.

Ao acessar o Swagger, serão são listados todos os serviços disponíveis, com a descrição do serviço, parâmetros e urls:

Expandir

title	Segurança e Autenticação

As APIs disponibilizadas no Swagger utilizam o Basic Authentication, que é o sistema de autenticação mais comum no protocolo HTTP.
Na tela de parâmetros da Lib DN , que é - pré-requisito para todas as customizações , - existe um processo que permite gerar o Token de forma simples.

Para isso, basta acessar o TOTVS Educacional | Customização | Parâmetros Gerais, conforme imagem abaixo:Image Removed

Na tela que se abrirá, existe um processo "Gerar Token". Nele, será solicitado o usuário e senha para login no TOTVS Educacional, que será utilizado para a autenticação nas APIs disponibilizadas. Ao finalizar a execução do processo, o Token será gerado no campo "Basic Auth", no formato Basic xxxxxxxx, conforme imagens abaixo:

Image Removed

Usuário e senha para geração do Token:

Image Removed

O conteúdo do Token gerado será salvo no campo "Basic Auth" na tela de "Parâmetros Gerais".

Image Removed

instruções e exemplos de geração, acesse o link Manual Operacional da Customização - LIB DN.

O Token deve ser enviado em todas as requisições no cabeçalho HTTP "Authorization".

Expandir

title	Exemplos de consumo das API's

Seguem exemplos do consumo de um serviço customizado disponibilizado no Swagger.

Expandir

title	Web Service Consulta SQL

Executa consultas SQL's cadastradas no RM e retorna o resultado em JSON.

Tipo: GET

Método: ExecutaConsultaSQL

Parâmetros:

codColigada (obrigatório): A coligada da sentença SQL cadastrada no RM.
codSentenca (obrigatório): O código da sentença SQL.
parameters (opcional): Parâmetros que são utilizados na consulta.

Exemplo: codColigada=0;email="[email protected]"

Obs.: Se a consulta não possuir parâmetros, o campo deve ser enviado sem nenhum valor.

codSistema (obrigatório): Código do sistema em que a consulta foi cadastrada. (Para consultar a lista com os códigos dos sistemas, clique aqui.)

Visualização do método no Swagger:

Image Added

Requisição no Postman

No Postman, devemos adicionar duas informações no cabeçalho (Header) da requisição: o Token (Authorization) e o Content-Type, para informar o tipo de dados utilizados, que, no caso das APIs da customização, é o JSON.

Image Added

Neste exemplo, executamos uma consulta que retorna os Municípios (Tabela GMUNICIPIO), sendo passado como parâmetro o Estado (CODETD).

Image Added

Exemplo do retorno no Postman:

Image Added

Exemplo das requisições em algumas linguagens de programação:

C# (Utilizando a biblioteca RestSharp)

Bloco de código

language	c#
firstline	1

var client = new RestClient("http://localhost:8080/rm/api/TOTVSCustomizacao/ConsultasSQL/ExecutaConsultaSQL?codColigada=2&codSentenca=CST.CONSULTA01&parameters=CODETD=MG&codSistema=A");
var request = new RestRequest(Method.GET);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Basic bWVzdHJlOnRvdHZz");
IRestResponse response = client.Execute(request);

PHP

Bloco de código

language	php
firstline	1

<?php

$request = new HttpRequest();
$request->setUrl('http://localhost:8080/rm/api/TOTVSCustomizacao/ConsultasSQL/ExecutaConsultaSQL');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'codColigada' => '2',
  'codSentenca' => 'CST.CONSULTA01',
  'parameters' => 'CODETD=MG',
  'codSistema' => 'A'
));

$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'Basic bWVzdHJlOnRvdHZz'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

NodeJS (Utilizando biblioteca Request)

Bloco de código

language	js
firstline	1

var request = require("request");

var options = { method: 'GET',
  url: 'http://localhost:8080/rm/api/TOTVSCustomizacao/ConsultasSQL/ExecutaConsultaSQL',
  qs: 
   { codColigada: '2',
     codSentenca: 'CST.CONSULTA01',
     parameters: 'CODETD=MG',
     codSistema: 'A' },
  headers: 
   { 'Content-Type': 'application/json',
     Authorization: 'Basic bWVzdHJlOnRvdHZz' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Âncora

	_CodSistema
	_CodSistema

Lista Códigos dos Sistemas

Nome	Código do Sistema
RM Custos	0
RM Chronus	A
RM Testis	B
RM Saldus	C
RM Liber	D
RM Classis - E	E
RM Fluxus	F
RM Bis	G
RM Agilis	H
RM Bonum	I
RM Factor	K
RM Biblios	L
RM Solum	M
RM Officina	N
RM Saude/Janus	O
RM Labore	P
RM SSO	R
RM Classis Net	S
RM Nucleus	T
RM Classis - U	U
RM Vitae	V
RM Portal	W
RM SGI	X
RM Acesso	Y

Expandir

title	Erros FIERGS EJA

Ao montar o ambiente do projeto foram encontrados alguns erros ao logar no Novo portal do aluno. Assim que o login era realizado, automaticamente o acesso expirava. Tivemos que recorrer ao documento do tdn que especifica os dados a serem tratados.

Foi verificado também que os arquivos estavam em pasta externa ao diretório comum para as customizações gerando erros.

Importante ressaltar que as customizações devem ficar dentro das pastas C:\RM\Legado\{versão}\FrameHTML\web\app\Cst como abaixo:

Image Added

Com esse padrão disposto, as referências do projeto devem ser direcionadas para ser as mesmas do ambiente FrameHTML que fica em: C:\RM\Legado\12.1.27\FrameHTML\web\js com isso, as referências serão atualizadas todas as vezes que o ambiente for atualizado.

Expandir

title	Erros PORTAL SESI

Ao realizar os testes na Federação do Amazonas, não estava sendo possível realizar a chamada para API de Consulta SQL.

Foi verificado que no IIS que a autenticação básica estava habilitada.

Ao desabilitar funcionou corretamente. Como desabilitar:

Image AddedO token deverá ser enviado em todas as requisições no cabecalho HTTP "Authorization". Nos tópicos abaixo serão apresentados exemplos de utilização via POSTMAN e via código em diferentes linguagens.

Informações

icon	false

Informações

icon	false

Produto: Customizações

Informações

icon	false

Versão: 12.1.17 ou Superiores

Data:2130/0208/2019

Informações

icon	false
title	Autores

Ana Carolina Eleutério Abras

Pedro Antonio Silva Barroso

Usuário desconhecido (thiago.chagas)

Atalhos

Páginas filhas

Versões comparadas

Versão antiga 12

Nova versão Atual

Chave

Documentação do Swagger

e consumo de API's

Atalhos

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 12

Nova versão Atual

Chave

Documentação do Swagger

e consumo de API's