O que é OpenAPI? Vantagens, Desvantagens & Exemplos

O que é OpenAPI?

De acordo com o SmartBear, a empresa-mãe do Swagger:

“A Especificação do OpenAPI (EOA) define uma interface padrão, independente da linguagem, para APIs RESTful que permite que humanos e computadores descubram e compreendam as capacidades do serviço sem acesso ao código-fonte, à documentação ou à inspeção do tráfego de rede.”

Esta definição é um pouco complicada. Vamos decompor a descrição do SmartBear em pedaços menores:

1.“…define uma intercafe padrão…”:

A especificação do OpenAPI define a estrutura de uma API que também descreve a API.

2. “…interface padrão de linguagem para APIs RESTful…”:

• REST APIs usam protocolo HTTP para transmissão de dados. Este protocolo permite que plataformas e sistemas escritos em diferentes linguagens de programação interajam.
• O OpenAPI lida apenas com APIs RESTful e não com outros tipos de APIs.

3. “…Que permite que pessoas e computadores descubram e compreendam as capacidades do serviço…”:

• As pessoas podem ler a documentação gerada diretamente a partir da definição da OAS de uma API.
• Um cliente entende como pode enviar solicitações e como os servidores API respondem a essas solicitações com base na definição de API.

4. “…Sem acesso ao código-fonte, à documentação ou à inspeção do tráfego de rede.”

Com a OpenAPI, o aplicativo do cliente e o servidor de API são separados. A definição de API de um serviço define como os clientes podem interagir com ele sem a necessidade de o cliente ler seu código-fonte.

Em resumo, a OpenAPI é uma especificação de API RESTful que descreve APIs em conformidade com a arquitetura RESTful. Uma especificação fornece uma interface para permitir que humanos e computadores entendam uma API e como interagir com ela.

História da OpenAPI

As origens da OpenAPI começaram com o engenheiro Tony Tam, da empresa Wordnik, em 2009. Tony criou uma especificação (chamada Swagger na época) que descreveria a API JSON do dicionário on-line da Wordnik.

O Swagger foi submetido a várias iterações por Tony nos anos seguintes. No entanto, o Swagger 2.0 registrou um aumento na adoção da especificação e desencadeou a criação de ferramentas para analisar a especificação.

Em 2015, a SmartBear adquiriu o Swagger. A SmartBear é a empresa que atualmente é proprietária do Swagger. A especificação Swagger foi renomeada como “OpenAPI” para refletir a nova iniciativa OpenAPI. Essa renomeação é a razão pela qual o “Swagger” é confundido com o padrão “OpenAPI”.

Na época, um grupo de empresas reconheceu que o setor precisava de uma forma padronizada e neutra em relação aos fornecedores para descrever as APIs. O setor precisava fornecer “práticas recomendadas” para o setor e supervisionar as atualizações da OpenAPI ao longo do tempo.

Essas empresas estabeleceram a Iniciativa OpenAPI como um programa de governança da Linux Foundation que mantém o padrão OpenAPI e fornece orientações práticas. As empresas fundadoras que formaram a iniciativa OpenAPI foram CapitalOne, PayPal, SmartBear, IBM, 3Scale, Google, Apigee, Intuit, Microsoft e Restlet. Desde então, o número de empresas que participam da iniciativa cresceu consideravelmente.

O Comitê de Direção Técnica agora gerencia a OpenAPI e continua a lançar novas versões com base no feedback da comunidade.

Por que o OpenAPI é um padrão popular?

Existem várias especificações disponíveis que descrevem APIs RESTful. O OpenAPI está entre os mais bem conhecidos e amplamente utilizados. Os outros dois formatos usados para REST APIs são RAML e API Blueprint. Abordaremos as vantagens e desvantagens do OpenAPI mais tarde. Embora o OpenAPI possa ser considerado o padrão da indústria, no final, as empresas muitas vezes escolhem o formato que melhor se adapta às suas necessidades de negócios.

Então, isso requer a pergunta: se há vários formatos disponíveis para descrever REST APIs, por que a OpenAPI é tão especial? Um fator chave para porque o OpenAPI é tão popular é a sua adoção. Mais adoção leva a mais apoio comunitário, ferramentas robustas e uma governação mais eficaz.

Uma empresa pode usar a especificação do OpenAPI para sua portabilidade e simplicidade. A OpenAPI é “language-agnostic” e define uma linguagem comum para a comunicação cliente-servidor. É altamente compatível com sistemas escritos em diferentes linguagens de programação. A OpenAPI também é altamente legível para seres humanos e computadores e tem o apoio de uma grande comunidade em crescimento.

Outro formato popular é o RAML, uma linguagem de modelagem de API com foco na definição e no design de APIs (embora você possa projetar APIs com OpenAPI). Os recursos da RAML podem parecer inferiores aos da OpenAPI. Ela tem a vantagem de ser hierárquica e suportar a herança do modelo de dados. No entanto, a RAML não é tão amplamente adotada quanto a OpenAPI. Embora a RAML tenha uma comunidade dedicada, ela tem menos suporte da comunidade. A RAML tem ferramentas, mas há algumas indicações de que as versões mais recentes não têm o suporte necessário.

Além da RAML, o API Blueprint é outra alternativa à OpenAPI. O API Blueprint se concentra em uma documentação clara com base no formato markdown, em vez de JSON (como OpenAPI) ou YAML (como OpenAPI e RAML). Devido à sua baixa adoção, o API Blueprint não tem suporte da comunidade e ferramentas robustas para OpenAPI. A integração do API Blueprint em todo o ciclo de vida da API é difícil porque seu único foco é a documentação.

Em resumo, a OpenAPI é o padrão mais popular para a descrição de APIs. Embora tenha desvantagens, a adoção da OpenAPI provavelmente crescerá, enquanto a viabilidade de longo prazo de outros tipos de especificação é incerta.

Como o OpenAPI define uma API?

Pense em um documento de especificação de legado que você leria no formato Microsoft Word (.docx). Esse documento de especificação de legado fornece o contexto geral de um sistema e descreve seus componentes e interações com outros sistemas.

A estrutura das especificações do legado geralmente varia. Uma especificação de API, como a OpenAPI, é estritamente estruturada. Se uma especificação de API estiver em conformidade com outro formato, como RAML ou API Blueprint, a documentação terá uma estrutura que adere a esse formato.

Voltando à forma como a OpenAPI define uma API, você ouvirá com frequência “especificação” e “definição” usadas como sinônimos. Uma especificação de API “define” uma API. Ao ler uma especificação de API, você aprende sobre os tipos de solicitações que pode enviar e as respostas que espera receber da API. Além disso, a especificação descreve as opções disponíveis que afetam as informações retornadas. Como em uma especificação herdada, você aprende sobre um sistema, seus componentes e suas interações.

Outra diferença entre as especificações de legado e as especificações de API é que as especificações de API são dinâmicas. Sempre que o código-fonte subjacente de uma API é alterado, a documentação é atualizada. Os documentos de especificação herdados exigem a atualização manual de documentos do Word sempre que o sistema é alterado.

Formato do OpenAPI

Antes de entender a estrutura de uma especificação da OpenAPI, você deve entender o formato de um documento da OpenAPI. Ao contrário das especificações legado escritas em Word, o formato da OpenAPI é JSON. Embora a discussão das nuances do JSON esteja fora do escopo desta postagem do blog, pense no JSON como uma forma de representar os dados de uma API como pares de valores-chave.

Por exemplo, em especificações legadas, você escreveria o título de uma especificação (incluindo o nome do sistema) usando um estilo de título na página de rosto. Para escrever o título de uma especificação da OpenAPI, por outro lado, você escreveria o título como um par de valores-chave JSON.

Agora, pense em todas as informações sobre uma API. Seus métodos, operações, respostas, etc. Imagine todas essas propriedades documentadas em uma série desses pares de valores-chave que seguem a estrutura da OpenAPI.

Observação: embora o JSON seja o formato padrão da OpenAPI, é possível representar a OpenAPI em YAML (um acrônimo que significa YAML não é linguagem de markup) mais simples.

Tipos de Dados

Como um objeto JSON, a especificação OpenAPI é compatível com os tipos de dados definidos na especificação mais ampla do esquema JSON. Os primórdios incluem inteiros, números, booleanos e cadeias de caracteres. Você pode declarar o formato de um tipo de dados usando o formato da propriedade modificadora. Por exemplo, você pode declarar um inteiro como formato int32 ou int64, um número como float ou double, ou uma cadeia de caracteres como formato binário, de dados, de data e hora ou de senha. A OpenAPI também oferece suporte a modelos (objetos) definidos na especificação JSON mais ampla como objetos de esquema.

É importante observar que o JSON é o principal formato que as APIs REST usam para enviar e receber informações.

Estrutura

Até agora, compreendemos que:

• Uma especificação do OpenAPI é um objeto JSON.
• As propriedades de uma API são um conjunto de pares de valor-chave.
• Valores são tipos de dados definidos pela especificação JSON mais ampla.

Agora, é hora de discutir a estrutura do OpenAPI.

Como mencionado anteriormente, um documento OpenAPI está estritamente estruturado. Objetos ou matrizes de objetos de pares de chave-valor relacionados. Os objetos de alto nível de uma especificação do OpenAPI são como os capítulos de um documento de especificação legado.

Abaixo está um modelo OpenAPI com seções recolhidas para mostrar a estrutura geral. Toda seção tem propriedades, ou pares de valor chave, que fornecem metadados sobre a API.

O nível superior do OpenAPI, indicado pelos primeiros conjuntos de parênteses { }, é chamado de “objeto de documento”, porque contém todas as propriedades da OpenAPI.

Enquanto os documentos do OpenAPI devem estar de acordo com uma estrutura básica, o OpenAPI oferece alguma flexibilidade. Algumas das seções de alto nível são necessárias, enquanto outras não. Você vai notar especificações do OpenAPI para diferentes APIs podem se parecer um pouco diferentes.

Um documento OpenAPI pode conter as seguintes seções:

• Openapi – Um campo obrigatório definindo a versão específica do OpenAPI da API. Ferramentas usam o número da versão para analisar a especificação do OpenAPI para gerar documentação, por exemplo.
• Info – Um campo obrigatório contendo metadados. Ferramentas podem alavancar metadados de maneiras diferentes.
• Servers – Um array de objetos de servidor. Cada objeto de servidor contém os detalhes da conexão a um servidor. Este objeto contém a URL para o host do servidor e uma descrição do servidor.
• Paths– Um objeto obrigatório que contém os caminhos relativos para os pontos de extremidade separados da API. Um determinado caminho tem operações disponíveis para interação com a API como POST, GET, PUT, ou DELETE.
• Components– um objeto que contém esquemas reutilizáveis para corpos, esquemas de resposta e esquemas de segurança. Esquemas nesta seção são referenciados em certas partes da especificação, como o objeto de caminho, usando a tag $ref.
• Security– um objeto que declara o tipo de esquema de segurança que autoriza requisições. Um objeto de segurança é definido globalmente ou sobrescrito por operações individuais (esquema de segurança substituído).
• Tags – um objeto que contém metadados. Ferramentas que analisam a especificação podem alavancar este objeto. Por exemplo, você pode especificar a ordem que você gostaria que cada recurso API fosse exibido na documentação da sua API (em vez de em ordem alfabética).
• ExternalDocs – um objeto que fornece links para documentação adicional. Você pode usar este objeto para adicionar um link aos seus guias de usuário.

Schemas

Na parte inferior da sua documentação da API, existe normalmente uma seção Schemas que corresponde ao esquema descrito na seção de componentes da definição da API.
Esta seção é um glossário rápido para quando o leitor precisa ver os esquemas gerais no contexto mais amplo da API (não a sua utilização em operações específicas). Esquemas são objetos que contêm propriedades/metadados.
A seção de esquemas seguintes para a Swagger Petstore apresenta esquemas específicos. Order é um esquema que representa uma ordem feita para um animal de estimação na Swagger Petstore. Cada pedido tem seus metadados, incluindo seu Id, a data que foi enviada e o status do pedido.

Pontos fortes do OpenAPI

O OpenAPI tem as seguintes vantagens:

• Limpar documentação – o OpenAPI é conhecido por sua documentação legível para humanos e computadores.
• Idioma-agnóstico – Os clientes podem interagir com servidores da API sem saber a implementação do servidor. Outros formatos como Diagrama da API exigem código de terceiros no servidor e não fornecem nenhum deste código para você.
• Governança – A iniciativa OpenAPI mantém o padrão OpenAPI e é moderada pelos líderes da indústria.
• Ampla adoção – OpenAPI é o formato mais popular para descrever APIs REST. A extensão de sua adoção indica que a OpenAPI está aqui para o longo prazo. Uma especificação, como o Diagrama da API, sofre de falta de adoção.
• Ferramentas – Sendo o formato mais amplamente suportado, existe agora uma proliferação de ferramentas que alavancam o OpenAPI para gerar documentação, testes, etc. Outras especificações não têm suporte e manutenção do OpenAPI para ferramentas.

Fraquezas do OpenAPI

Cada tipo de especificação tem suas forças e fraquezas. Aqui, vamos nos concentrar nas desvantagens da OpenAPI em comparação com seu rival mais próximo, RAML.

Menos útil para design e planejamento da API

Você pode adotar uma abordagem “spec-first” para projetar uma API com base na OpenAPI. Essa abordagem envolve escrever a especificação da OpenAPI para uma API “à mão” ou usar uma ferramenta de design. Usando essa abordagem, você projeta a especificação de uma API e, em seguida, usa a especificação como um “contrato” ao criar a API. O oposto de “spec-first” é usar a OpenAPI para gerar documentação sem usá-la como uma ferramenta de design.

Embora a abordagem “spec-first” tenha muitas vantagens, a OpenAPI geralmente não vem antes do desenvolvimento da API.

A estrutura hierárquica da RAML pode se prestar mais a ser uma ferramenta de projeto e planejamento. Dessa forma, a RAML pode ser mais compatível com a abordagem “spec-first” do que a REST. No final, a RAML é comercializada como uma ferramenta de “modelagem de dados” e “descrição” de API, enquanto o Swagger é a última. O modelo hierárquico do RAML será discutido com mais detalhes na próxima seção.

Não Hierárquica

Um dos conceitos principais para os padrões de definição de API como OpenAPI e RAML é a capacidade de criar objetos de dados e relacioná-los entre si. O OpenAPI usa esquemas para este propósito e suporta os tipos de dados integrados do JSON. RAML usa um sistema de tipos para salvar propriedades associadas e promover a reutilização em toda a especificação. Também suporta os mesmos tipos de dados internos que o OpenAPI.

A OpenAPI não tem uma estrutura hierárquica “verdadeira”. O que você deseja de uma estrutura hierárquica que descreva sua API? Idealmente, você quer um sistema para associar seus modelos de dados que seja:

• legível/compreensível facilmente
• permite definir relações entre modelos de dados usando herança
• reduz a repetição de propriedades compartilhadas
• maximiza a reutilização de código

O sistema de tipos da RAML se presta a ser um sistema mais hierárquico do que o REST. De acordo com o Readme da RAML no GitHub, O uso da RAML de “tipos de recursos e características minimiza a repetição em um RESTful design API e promove a consistência dentro e através das APIs. Discutiremos a seguir o sistema de tipos da RAML.

Não suporta a herança do modelo de dados

Tipos de objeto RAML podem herdar outros tipos de objetos. Enquanto os esquemas OpenAPI podem “referenciar” esquemas, ele não suporta tecnicamente a herança como a RAML. Digo “tecnicamente” porque você pode ligar um esquema a outro usando uma referência do esquema (o marcador $ref). No entanto, a RAML vai mais longe. Você pode estabelecer relações entre modelos de dados e evitar a repetição de propriedades compartilhadas. Com OpenAPI, esquemas não estão associados uns aos outros de forma hierárquica como a RAML. Tipos RAML têm herança “verdadeira”, onde você pode estabelecer relações entre pais e filhos entre modelos de dados.

Não é uma ferramenta “visual”

O uso dos tipos RAML como modelos de dados o torna mais visual e facilmente legível do que o OpenAPI. Você pode ver facilmente a relação entre tipos e suas propriedades compartilhadas.

RAML, como uma ferramenta mais visual, promove um planejamento a longo prazo para coisas como respostas simuladas no servidor, consoles API e muito mais. Pode ser também antecipar e planejar futuras melhorias na API utilizando a RAML.

Falta de suporte para outras arquiteturas

A OpenAPI só pode descrever APIs RESTful. A RAML tem o benefício adicional de oferecer suporte a outras arquiteturas além da REST, como RPC ou SOAP, desde que usem o protocolo HTTP. A flexibilidade do RAML permite que você o use como uma ferramenta de documentação para arquiteturas além da REST.

Exemplo da OpenAPI – Swagger Petstore

A melhor maneira de aprender a OpenAPI é adoptar uma abordagem prática. Algumas ferramentas permitem editar especificações do OpenAPI e, em seguida, gerar documentação da API. A especificação Swagger Petstore é um exemplo de um documento OpenAPI.

SwaggerUI é uma ferramenta que analisa uma definição de API para gerar documentação. SwaggerUI tem um editor baseado no navegador (mostrado abaixo). Você pode experimentar o editor SwaggerUI aqui: https://editor.swagger.io/

No lado esquerdo, a especificação OpenAPI no formato YAML é visível. Sempre que você fizer alterações na especificação, essas alterações geram nova documentação no painel do lado direito. O painel do lado direito é o documento Swagger gerado diretamente a partir da especificação OpenAPI para o Petstore (painel do lado esquerdo). Por exemplo, mudar a descrição de um caminho faz com que o documento Swagger atualize com as novas alterações.

Se você olhar a especificação do Swagger OpenAPI à esquerda, você verá todas as seções descritas neste artigo do blog, incluindo openapi, informações, servidores, caminhos, componentes, tags, etc.

Swagger gera um erro quando você se desvia da estrutura do OpenAPI ou inserir algo inválido. A manipulação de erros do Swagger reforça o conceito que você deve aderir ao formato OpenAPI para exibir corretamente. Quando você se familiarizar com o Swagger Petstore, você pode colar a especificação para outra API no Swagger Editor para ver como suas informações são exibidas na SwaggerUI.

Em resumo, O Swagger Editor é uma ótima maneira de se familiarizar com como escrever definições de API e como ferramentas analisam a especificação para gerar documentação.

Leitura adicional

Para uma documentação mais aprofundada sobre o padrão OpenAPI, leia a documentação oficial do SmartBear para o OpenAPI: https://swagger.io/specification/.

Além disso, confira nosso guia para lançar API pública

Pronto para levar sua documentação de API para o próximo nível? Reserve uma demonstração com o Document360 hoje!

Reserve uma demonstração