Introdução
Uma API REST (Representational State Transfer ou Transferência de Estado Representacional) é uma interface que permite que diferentes aplicações se comuniquem entre si através do protocolo HTTP, usando operações padrão como GET, POST, PUT e DELETE. APIs REST são amplamente utilizadas no desenvolvimento de software para expor serviços acessíveis por outras aplicações, possibilitando a integração entre diferentes sistemas.
No entanto, para garantir que as APIs sejam fáceis de entender e usar, uma boa documentação é essencial. É aqui que o OpenAPI entra em cena.
OpenAPI é um padrão para descrever APIs RESTful. Ele permite uma definição estruturada da funcionalidade de uma API, especificando endpoints disponíveis, tipos de dados aceitos e retornados, parâmetros necessários e respostas esperadas. Todas essas informações são coletadas em um arquivo de especificação (geralmente com extensão .yaml ou .json), que pode ser interpretado por ferramentas automatizadas para gerar código, documentação e muito mais.
A Especificação OpenAPI é projetada para ser legível tanto por máquinas quanto por humanos, possibilitando a descrição, produção, consumo e visualização de serviços web RESTful de forma padronizada. Portanto, um documento OpenAPI representa uma descrição formal da API, útil tanto para desenvolvedores que precisam usá-la quanto para ferramentas que podem aproveitá-la para automatizar vários processos.
Por que é útil definir um arquivo de especificação?
Adotar o OpenAPI para documentar uma API oferece diversos benefícios:
- Clareza: Ele fornece documentação detalhada e estruturada, permitindo que os desenvolvedores entendam rapidamente como interagir com a API, quais requisições enviar e quais dados esperar em resposta.
- Automação: A documentação pode ser gerada automaticamente a partir do código, mantendo-se atualizada com quaisquer alterações na API.
- Interatividade: Ferramentas como o Swagger, um conjunto de código aberto para documentação e teste de APIs, incluem o Swagger UI. Isso permite explorar e testar APIs diretamente do navegador, simplificando o desenvolvimento, a verificação e a compreensão das APIs.
- Padronização: Usar o OpenAPI garante que a documentação siga um formato compartilhado e reconhecido, facilitando a integração com outras ferramentas e serviços.
Como você pode produzir um documento OpenAPI?
Existem duas abordagens principais para gerar um arquivo de especificação OpenAPI:
- Abordagem "Código-primeiro" (automática): Se uma API REST já foi desenvolvida no InterSystems IRIS, você pode gerar automaticamente a documentação OpenAPI sem escrever manualmente o arquivo de especificação. O IRIS oferece um recurso integrado para exportar a documentação OpenAPI em formato JSON ou YAML, com base nas definições de classe REST.
- Abordagem "Especificação-primeiro" (manual): Neste caso, o arquivo OpenAPI é escrito manualmente em YAML ou JSON, descrevendo todos os endpoints, parâmetros e respostas esperadas. Essa abordagem é útil quando você deseja definir a API antes de implementá-la, facilitando o design e o compartilhamento com outros desenvolvedores ou stakeholders.
Abordagem Automática
Existem duas maneiras de gerar automaticamente o arquivo de especificação OpenAPI no InterSystems IRIS.
Método 1: Usando a Função GetWebRESTApplication
Uma abordagem é usar a função GetWebRESTApplication fornecida pela classe %REST.API.
Um exemplo prático de como usá-la é adicionando a seguinte função na classe de despacho:
ClassMethod GenerateOpenAPI() As %Status
{
Set webApplication = "MyAPP"
Set sc = ##class(%REST.API).GetWebRESTApplication("", webApplication, .swagger)
If $$$ISERR(sc) {
Quit sc
}
Set %response.ContentType = "application/json"
Do ##class(OMRREST.impl).%WriteResponse(swagger.%ToJSON())
Quit $$$OK
}
Adicionalmente, adicione a seguinte rota ao UrlMap:
<Route Url="/openapi" Method="GET" Call="GenerateOpenAPI"/>
Neste ponto, você terá tudo o que precisa para gerar o arquivo de especificação a partir de sua classe de despacho. Para visualizar a documentação, conecte-se à URL mostrada (onde MyWebapp é o nome da sua aplicação web, conforme definido no portal de gerenciamento):
<host>:<port>/MyWebapp/openapi
O JSON gerado dessa forma representa a especificação OpenAPI da sua API. Após explorar o segundo método, veremos como visualizá-lo e testá-lo no Swagger.
Método 2: Usando a API de Gerenciamento
Outra maneira de gerar o arquivo de especificação OpenAPI é usando a API de Gerenciamento do InterSystems IRIS.
Para chamar este serviço, você pode usar ferramentas como o Postman, que é uma ferramenta de desenvolvedor que permite testar, documentar e automatizar APIs.O Postman fornece uma interface simples e intuitiva para enviar requisições HTTP (GET, POST, PUT, DELETE, etc.), visualizar respostas, gerenciar autenticação e criar testes automatizados.
Para fazer a requisição usando o Postman, siga estes passos:
- Clique no botão
Novo e crie uma requisição HTTP. .png)
- Configure a requisição da seguinte forma e envie-a:
.png)
Uma vez que o JSON é gerado, ele pode ser visualizado e testado usando ferramentas como o Swagger Editor.
{
"info":{
"title":"",
"description":"",
"version":"",
"x-ISC_Namespace":"MyNamespace"
},
"basePath":"/MyWebapp",
"paths":{
"/loginForm":{
"post":{
"parameters":[
{
"name":"payloadBody",
"in":"body",
"description":"Request body contents",
"required":false,
"schema":{
"type":"string"
}
}
],
"operationId":"loginForm",
"x-ISC_ServiceMethod":"loginForm",
"responses":{
"default":{
"description":"(Unexpected Error)"
},
"200":{
"description":"(Expected Result)"
}
}
}
},
"/refresh":{
"post":{
"parameters":[
{
"name":"payloadBody",
"in":"body",
"description":"Request body contents",
"required":false,
"schema":{
"type":"string"
}
}
],
"operationId":"refresh",
"x-ISC_ServiceMethod":"refresh",
"responses":{
"default":{
"description":"(Unexpected Error)"
},
"200":{
"description":"(Expected Result)"
}
}
}
},
"/logout":{
"post":{
"parameters":[
{
"name":"payloadBody",
"in":"body",
"description":"Request body contents",
"required":false,
"schema":{
"type":"string"
}
}
],
"operationId":"logout",
"x-ISC_ServiceMethod":"logout",
"responses":{
"default":{
"description":"(Unexpected Error)"
},
"200":{
"description":"(Expected Result)"
}
}
}
},
"/openapi":{
"get":{
"operationId":"GenerateOpenAPI",
"x-ISC_ServiceMethod":"GenerateOpenAPI",
"responses":{
"default":{
"description":"(Unexpected Error)"
},
"200":{
"description":"(Expected Result)"
}
}
}
}
},
"swagger":"2.0"
}
.png)
.png)
Abordagem Manual
A abordagem manual para gerar um documento OpenAPI envolve escrever o arquivo de especificação à mão no formato YAML ou JSON. Essa abordagem é particularmente útil quando você deseja controle completo sobre o design da API antes de sua implementação, ou ao documentar uma API já existente sem depender de ferramentas automatizadas
Para escrever o arquivo de especificação OpenAPI, você pode consultar a documentação oficial da versão 2.0 da Especificação OpenAPI, onde encontrará informações sobre campos obrigatórios e como descrever endpoints, parâmetros, respostas e muito mais. Este guia detalhado o ajudará a entender como estruturar adequadamente o arquivo YAML ou JSON para atender aos padrões OpenAPI.
Um bom exemplo de usar essa abordagem é ao criar um serviço REST usando os métodos descritos na documentação oficial do InterSystems IRIS.
Você pode encontrar uma introdução sobre como desenvolver e configurar uma aplicação REST no IRIS seguindo esta página da documentação, que descreve passo a passo os métodos necessários para expor uma aplicação RESTful com IRIS.
