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)

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

Image Removed

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

Para o erro da primeira imagem:

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.

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

.

Arquivo Web.Config

Na pasta No diretório "CX:\totvs\CorporeRM\FrameHTML", localize o arquivo de configurações "Web.Config". Verificar e colocar como Certifique-se que a tag "owin:AutomaticAppStartup " está com o valor "true" a seguinte tag:

Bloco de código

language	xml

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

Expandir

title	Visualizando a Documentação

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, são , serã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 instruções e exemplos de geração, acesse o link abaixo:link Manual Operacional da Customização - LIB DN.

O Token deverá deve ser enviado em todas as requisições no cabeçalho HTTP "Authorization". Nos tópicos abaixo serão apresentados exemplos de utilização via POSTMAN e via código em diferentes linguagens.

Expandir

title	Exemplos de consumo das APIsAPI's

Seguem A seguir, serão exibidos exemplos do consumo de um serviço customizado disponibilizado no Swagger. O método em que será feita a chamada é o ExecutaConsultaSQL, que realiza a execução de consultas SQL cadastradas no RM

Expandir

title	Web Service Consulta SQL

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

O método utilizado é GET, e existem 4 parâmetros:

codColigada (Código da Coligada da Sentença SQL)
codSentenca (Código da Sentença)
parameters (Parâmetros que são utilizados na consulta)
codSistema (Código do sistema onde a consulta foi cadastrada)

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

Segue a visualização

do método no Swagger:

Image Modified

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 Modified

Neste exemplo,

vamos executar

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

Image Modified

Exemplo do retorno no Postman:

Image Modified

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 Added

Informações

icon	false

Informações

icon	false

Produto: Customizações

Informações

icon	false

Versão: 12.1.17 ou Superiores

Data:30/08/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 18

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 18

Nova versão Atual

Chave

Documentação do Swagger

e consumo de API's