O que é OpenAPI?

Um arquivo OpenAPI, também conhecido como documento OpenAPI ou especificação OpenAPI, permite que um desenvolvedor descreva uma API. Essa especificação também descreve como usar essa API, incluindo endpoints disponíveis, parâmetros de operação, métodos de autenticação e outras informações. Essas especificações são escritas em YAML ou JSON, e o esquema JSON é usado para descrever os formatos de dados em uma API.

O OpenAPI serve tanto como documentação quanto como um contrato (em essência, descrevendo o que uma API deve fazer; ele não é legalmente vinculativo) entre consumidores e produtores de API. Basicamente, serve como "uma fonte de verdade" que fornece as instruções em um formato padronizado.

Essa padronização simplifica o consumo e a integração de APIs. Isso permite que humanos e computadores entendam a função e a estrutura de uma determinada API sem acesso ao código-fonte ou a necessidade de entender o funcionamento interno da API. Também permite que os desenvolvedores trabalhem com uma API, independentemente da linguagem em que ela foi escrita.

O OpenAPI automatiza a documentação interativa e atualizada, eliminando um trabalho repetitivo de documentação e ajudando a garantir que a documentação permaneça atualizada. O OpenAPI também permite a geração de código para SDKs de clientes e a geração de outros códigos padrão automaticamente a partir da especificação, reduzindo o erro humano e minimizando ainda mais a carga de trabalho do desenvolvedor.

Ferramentas que usam especificações OpenAPI, incluindo o SwaggerUI, podem renderizar uma especificação de API em uma interface interativa. Essa interface não apenas ajuda a visualizar a especificação, mas também permite chamadas de API reais, diretamente do navegador ou serviço da web, para fins de teste e validação.

Ao padronizar a forma como as APIs REST são descritas, o OpenAPI ajuda a melhorar a interoperabilidade e as ferramentas, além de dar suporte às operações durante todo o ciclo de vida da API. Uma especificação forte e bem mantida pode ser uma ferramenta fundamental para implementar uma estratégia de API abrangente, apoiando a integração, colaboração, prevenção de erros e um gerenciamento de API mais forte.

A especificação completa pode ser encontrada no GitHub.

Como padrão de fato do setor, o OpenAPI fornece um documento seguro, automatizado e amplamente compreendido para o desenvolvimento de API.

O OpenAPI foi originalmente criado pelo desenvolvedor Tony Tam e lançado pela primeira vez em 2011 sob o nome de Swagger. Na época, as especificações de API eram frequentemente documentos estáticos que exigiam atualizações tediosas e estavam frequentemente desatualizados. A especificação Swagger incluiu várias inovações no desenvolvimento da API, incluindo um botão "experimente" para testar chamadas de API ao vivo e em tempo real.

O Swagger fez da documentação um foco de sua existência. Isso permitiu que os desenvolvedores incluíssem anotações, semelhantes a uma nota adesiva, no código-fonte. O Swagger pode ler essas anotações e atualizar a documentação automaticamente, garantindo que a documentação permaneça atualizada sem o trabalho tedioso e repetitivo de atualização.O Swagger também introduziu um formato para descrever APIs em JSON legível por máquina, o que o tornou independente de linguagem: independentemente da linguagem de um back-end, o Swagger produziria um arquivo JSON universal.

O Swagger foi adquirido pela SmartBear Software em 2015, teve seu nome alterado para OpenAPI logo em seguida e foi doado à nova OpenAPI Initiative (OAI), sob a égide da Linux Foundation. A versão atual é OpenAPI 3.1.

A especificação do OpenAPI é um documento padronizado, legível por humanos e máquinas, que define a estrutura e a sintaxe das APIs. Todos os documentos OpenAPI incluem determinados componentes e estão em conformidade com a mesma estrutura básica, mas algumas especificações contêm mais informações do que outras. No mínimo, uma especificação deve incluir os camposopenAPI einfo e, pelo menos, um campopath , component ou webhook .¹

openAPI: indica a versão do OpenAPI que o documento utiliza, como por exemplo, "3.1.1".

informações: inclui metadados gerais da API, como o título e o número da versão da API, uma descrição da API, termos de serviço e informações de contato.

servidores: uma lista de URLs base onde a API pode ser acessada (que pode incluir ambientes de teste e produção). Essa lista inclui variáveis para hosts específicos do ambiente.

caminhos: descreve os caminhos e os métodos HTTP associados (ou operações, por exemplo, GET, PUT, POST) e os parâmetros, corpos de solicitação e respostas para cada item do caminho.

componentes: lista os objetos reutilizáveis, como esquemas de dados, parâmetros, respostas, cabeçalhos e definições de segurança. Esses objetos podem ser referenciados em todo o documento. Os componentes são referenciados, de forma simples, com $ref. Essa estratégia mantém o projeto da API o mais simplificado possível.

security: indica os esquemas de segurança e os mecanismos de autenticação que a API usa, como o OAuth ou chaves de API. Também permite a aplicação de esquemas de segurança globalmente ou por operação.

tags: lista de alto nível de tags que são usadas para organizar as operações. O uso de etiquetas pode ajudar a melhorar a clareza do documento (por exemplo, "Usuários" ou "Pedidos").

documentação externa: links para guias, documentos de integração e outras documentações externas para a API

webhooks: descreve as chamadas de entrada que a API recebe.

O OpenAPI fornece uma fonte única da verdade para desenvolvedores e consumidores de APIs, além de oferecer recursos que agregam valor e eficiência aos projetos de API.

O OpenAPI foi criado inicialmente com um forte foco na documentação de APIs REST, e esse foco permanece em sua essência até hoje. A documentação é padronizada, interativa, atualizada em tempo real e fornece um contrato com uma fonte única da verdade.

Existem diversas ferramentas para ler a documentação do OpenAPI e exportar o código. Uma dessas ferramentas é o Swagger Codegen, que lê documentos escritos de acordo com a especificação do OpenAPI. O Swagger Codegen pode então produzir kits de desenvolvimento de software (SDKs) de código de cliente de API, código do lado do servidor (stubs) e páginas da web legíveis com documentação atualizada que são legíveis por humanos.

Uma das funcionalidades mais inovadoras do OpenAPI continua sendo o botão "experimente", que permite testes e validação em tempo real diretamente de um navegador. O Swagger UI, uma ferramenta gratuita de código aberto, permite uma interface visual na qual um desenvolvedor pode enviar solicitações reais para ajudar a garantir que elas respondam conforme desejado. Essa ferramenta facilita a verificação instantânea de que uma solicitação está funcionando.

O OpenAPI é comumente usado com plataformas de integração como serviço, ou iPaaS.

As plataformas iPaaS usam especificações OpenAPI para entender e conectar diferentes aplicações em um ecossistema de TI. Quando as aplicações expõem especificações OpenAPI que descrevem suas APIs, as plataformas iPaaS podem usar essas informações para descobrir automaticamente endpoints, métodos de autenticação e estruturas de dados. Essa estratégia agiliza a criação de integrações, como conectar uma plataforma de comércio eletrônico a um software de contabilidade.

O OpenAPI também permite que desenvolvedores de front-end e back-end trabalhem em paralelo. O trabalho em paralelo é preferível a, como às vezes acontece, a equipe de front-end ser obrigada a esperar até que a equipe de back-end tenha seu banco de dados em funcionamento. Com um contrato OpenAPI, a equipe de front-end pode criar um servidor de API simulado que se comporta como um servidor real, permitindo e otimizando os testes antes que o desenvolvimento de back-end seja concluído.

A governança de API, as normas, políticas e práticas que orientam como uma organização desenvolve e usa APIs, é vital para ajudar a garantir que as APIs operem sem dificuldades, de forma consistente e sem repetições desnecessárias. Como o OpenAPI atua como um contrato entre desenvolvedores, a governança e a segurança podem ser incorporadas desde o início.

Tomemos como exemplo os API gateways, que lidam com tarefas como roteamento de tráfego, monitoramento e limitação de taxa. Os API gateways normalmente podem consumir especificações OpenAPI e impor quaisquer limites de tráfego ou outras medidas de segurança estabelecidas na especificação.

O mesmo se aplica às regras de segurança. Uma especificação OpenAPI permite que os desenvolvedores declarem os requisitos de segurança (como o uso de OAuth 2.0 e chaves de API), e esses requisitos podem ser aplicados mais adiante (por um gateway, talvez).Definir as funcionalidades de segurança em um contrato de API ajuda a garantir que os desenvolvedores não implementem esquemas de segurança não suportados.

O OpenAPI pode fortalecer o gerenciamento da API, o processo escalável de criação, publicação e gerenciamento de conexões de API, de várias maneiras. Por exemplo, como as especificações do OpenAPI são legíveis por máquina e padronizadas, o software de catálogos e portais pode indexá-las automaticamente. Essa padronização torna as APIs mais fáceis de encontrar e entender em uma organização. Essa capacidade de descoberta ajuda a evitar que as equipes criem APIs duplicadas sem saber.

O OpenAPI também oferece suporte à gestão e governança consistentes, tornando os padrões organizacionais explícitos e aplicáveis. As equipes podem definir requisitos, como convenções de versionamento, formatos de resposta a erros ou padrões de nomenclatura, diretamente na especificação ou em conjunto com ela. Como essas expectativas são documentadas em um formato padronizado, elas podem ser validadas automaticamente em relação a novas APIs à medida que são adicionadas. Essa validação reduz a dependência de avaliações manuais e ajuda a garantir que as APIs permaneçam consistentes à medida que o portfólio de uma organização cresce.