Especificações de Geração de OpenAPI

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
{
    // The name of the REST application
    Set webApplication = "MyAPP"  // Replace with the name of your web app
    // Retrieve the OpenAPI 2.0 documentation
    Set sc = ##class(%REST.API).GetWebRESTApplication("", webApplication, .swagger)
    
    If $$$ISERR(sc) {
        Quit sc  // If an error occurred, exit the method
    }
    
    // Return the documentation in JSON format
    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:

1. Clique no botão Novo e crie uma requisição HTTP.
2. Configure a requisição da seguinte forma e envie-a:
   • Selecione GET como o método HTTP.
   • Especifique a URL no seguinte formato, usando o <baseURL> da sua instância:

     https://<baseURL>/api/mgmnt/v1/namespace/myapp

     Aqui, namespace é o nome do namespace onde você criou o serviço REST, e myapp é o nome da sua aplicação web.
   • Defina o método de Autorização para Basic Auth e forneça o nome de usuário e senha de um usuário com acesso de leitura ao namespace especificado.

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"
}

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.