Tutorial OpenAPI 3.0: Definição da Especificação OpenAPI
Aprenda a definir a Especificação OpenAPI neste tutorial para documentação consistente e precisa de suas APIs RESTful usando OpenAPI 3.0.
Você precisa de ajuda para desenvolver e documentar APIs para projetos grandes ou complexos? Não tema! Temos a solução perfeita para você - a Especificação OpenAPI (anteriormente conhecida como Especificação Swagger). Este padrão livre e de código aberto torna o desenvolvimento e a documentação da API um pedaço de bolo! Com o OpenAPI, você pode facilmente criar e documentar APIs usando um formato padronizado que é fácil de entender.
Economize tempo tentando descobrir o complexo desenvolvimento e documentação de APIs. Deixe-nos ajudá-lo a simplificar o processo com o OpenAPI!
O que é a Especificação OpenAPI (OAS)
OpenAPI é uma especificação que define a estrutura de uma API RESTful e descreve suas capacidades. A Especificação OpenAPI fornece uma forma padrão de documentar e interagir com APIs, permitindo que os desenvolvedores descubram e entendam como elas funcionam de maneira eficiente. As APIs RESTful usam o protocolo HTTP para transmissão de dados, facilitando a comunicação entre plataformas e sistemas escritos em diferentes linguagens de programação.
Com o OpenAPI, você não precisa de acesso ao código-fonte ou inspeção de tráfego de rede para entender como uma API funciona. A própria definição da API fornece todas as informações necessárias.
Formato OpenAPI
A versão mais recente do OpenAPI é 3.0. As definições OpenAPI podem ser escritas em JSON ou YAML. O JSON representa dados usando pares chave-valor em vez de escrever uma descrição longa da API e seguir a estrutura OpenAPI. Isso facilita a compreensão das capacidades de uma API, mesmo que você não tenha acesso ao código-fonte ou à documentação.
Exemplo de especificação OpenAPI 3.0 no formato JSON:
{
"openapi": "3.0.0",
"info": {
"title": "Título da API",
"description": "Descrição da API",
"version": "1.0.0"
}
}
}
Por exemplo, Na documentação tradicional, você escreveria uma seção separada para cada método de API, descrevendo o que faz e como usá-lo. O OpenAPI adota uma abordagem diferente ao organizar essas informações em uma série de pares chave-valor. Cada método tem um conjunto de propriedades que o descrevem, incluindo parâmetros de solicitação e códigos de resposta.
Embora o JSON seja o formato padrão para OpenAPI, você também pode usar YAML, uma linguagem de marcação mais simples. Isso facilita ainda mais a criação e edição de documentos OpenAPI.
openapi: 3.0.0
info:
title: Título da API
description: Descrição da API
version: 1.0.0
Então aí está - o básico do OpenAPI. Pode parecer um pouco técnico inicialmente, mas assim que você pegar o jeito, você se perguntará como já viveu sem isso.
A especificação OpenAPI utiliza tipos de dados JSON definidos na Especificação JSON Schema. Esses tipos de dados incluem inteiros, números, booleanos e strings. Você também pode modificar o formato desses tipos de dados usando a propriedade 'format', como int32, int64, float, double, binary, data, date-time e formato de senha. O OpenAPI também permite o uso de modelos (objetos) definidos sob a especificação JSON como objetos de esquema.
Estrutura OpenAPI
A especificação OpenAPI é um documento que descreve a estrutura e o comportamento das APIs REST. Vamos nos aprofundar no documento OpenAPI.
Um documento OpenAPI tem um formato estruturado composto por objetos ou arrays de objetos que agrupam pares chave-valor relacionados. O primeiro conjunto de colchetes {} em um documento OpenAPI contém todas as propriedades e é chamado de "objeto do documento". Embora haja alguma flexibilidade, os documentos OpenAPI devem aderir a uma estrutura básica. Algumas seções de alto nível são obrigatórias, enquanto outras são opcionais, permitindo variações nas especificações OpenAPI entre diferentes APIs.
Um documento OpenAPI pode conter as seguintes seções:
- OpenAPI: A API requer a especificação da versão OpenAPI para permitir que as ferramentas analisem a especificação OpenAPI e gerem documentação.
- Info: Este campo contém metadados sobre a API, como seu título, descrição e versão. Várias ferramentas podem aproveitar essas informações.
- Servers: Este campo na Especificação OpenAPI consiste em um array de objetos de servidor, cada um contendo uma URL para o host do servidor e uma breve descrição do servidor. Essas informações fornecem detalhes de conexão que você pode usar para interagir com o servidor.
- Paths: Este objeto contém os caminhos relativos para os endpoints separados da API. Cada caminho inclui operações disponíveis para interagir com a API, como POST, GET, PUT ou DELETE.
- Components: Este campo na Especificação OpenAPI é um objeto que contém esquemas reutilizáveis para corpos de solicitação, esquemas de resposta e esquemas de segurança. Esses esquemas podem ser referenciados ao longo da especificação usando a tag $ref, particularmente no objeto de caminho.
- Security: Um objeto que declara o tipo de esquema de segurança que autoriza solicitações. Um objeto de segurança é definido globalmente ou substituído por operações individuais.
- Tags: Um objeto que contém metadados que especificam a ordem na qual você deve exibir os recursos da API na documentação.
- ExternalDocs: Um objeto que fornece links para documentação adicional, como guias do usuário.
Aqui está o modelo básico para um documento OpenAPI com os campos obrigatórios no formato YAMLJSON.
Solicitação POST
O seguinte endpoint de exemplo para uma solicitação POST para upload de uma imagem de um animal de estimação é definido.
openapi: 3.0.3
info:
title: Swagger Petstore - OpenAPI 3.0
version: 1.0.11
servers:
- url: https://petstore3.swagger.io/api/v3
tags:
- name: pet
description: Tudo sobre seus Pets
paths:
/pet/{petId}/uploadImage:
post:
tags:
- pet
summary: faz upload de uma imagem
description: ''
operationId: uploadFile
parameters:
- name: petId
in: path
description: ID do pet a ser atualizado
required: true
schema:
type: integer
format: int64
- name: additionalMetadata
in: query
description: Metadados adicionais
required: false
schema:
type: string
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: operação bem-sucedida
Você pode executar o código acima em https://editor.swagger.io/. O seguinte será a saída.
O trecho de código começa fornecendo informações básicas sobre a API, como seu título e versão. Ele também especifica a URL base para o servidor da API.
A seção tags define uma tag chamada "pet" que agrupa todos os endpoints relacionados a animais de estimação. A seção paths contém a definição para o endpoint /pet/{petId}/uploadImage.
O endpoint /pet/{petId}/uploadImage suporta um método POST para fazer upload de uma imagem de um pet. A seção de parâmetros define dois parâmetros, "petId" e "additionalMetadata," que especificam o ID do pet a ser atualizado e quaisquer metadados adicionais para a imagem carregada, respectivamente.
A seção request body especifica a estrutura do corpo da solicitação, que deve estar em formato binário. A seção de respostas define um único código de resposta, 200, indicando a operação bem-sucedida.
Quais são os benefícios do OpenAPI?
A Especificação OpenAPI oferece vários benefícios para desenvolvedores que constroem e documentam APIs.
A Especificação OpenAPI simplifica o desenvolvimento de APIs por meio de melhor colaboração, consistência, geração de código, validação e ferramentas. Uma forma padronizada e transparente de descrever APIs simplifica a colaboração entre as equipes enquanto assegura a consistência na documentação da API.
Os desenvolvedores podem gerar código para APIs em várias linguagens de programação, mantendo consistência entre as linguagens. Os arquivos de documentação gerados são confiáveis e consistentes, além de economizar tempo para os desenvolvedores.
As ferramentas de validação ajudam a garantir compatibilidade e prevenir erros, enquanto um rico ecossistema de ferramentas simplifica todo o processo de desenvolvimento de APIs. A Especificação OpenAPI reduz erros e melhora a qualidade dos projetos de software resultantes.
Como Criar a Especificação OpenAPI
Mas e se você preferir evitar escrever código manualmente? Não se preocupe, estamos aqui para ajudar! Apidog é uma ferramenta que torna o trabalho com a Especificação OpenAPI muito fácil. É uma plataforma baseada em nuvem que simplifica o projeto, teste e publicação de APIs. Com isso, os desenvolvedores podem criar e editar especificações OpenAPI usando um editor visual intuitivo.
Apidog também inclui testes integrados que permitem que os desenvolvedores testem suas APIs diretamente da plataforma. Ela fornece um marketplace de APIs onde os desenvolvedores podem descobrir e usar APIs pré-construídas de outros desenvolvedores. Com isso, você pode rapidamente adicionar caminhos, parâmetros e respostas às suas APIs usando uma interface intuitiva.
A melhor parte? Apidog gera documentação automaticamente. Com apenas alguns cliques, você pode criar uma documentação bonita para sua API com base em sua especificação OpenAPI. A documentação inclui informações sobre cada endpoint, incluindo seus parâmetros, respostas e exemplos.
Vamos dar uma olhada em um guia passo a passo sobre como podemos fazer isso. Aqui está um processo passo a passo para importar um arquivo de especificação OpenAPI no Apidog:
Passo 1. Abra o site Apidog
Primeiro, abra o site Apidog em seu navegador. Você pode acessá-lo visitando o site deles.
Passo 2. Faça login na sua Conta
Se você já tem uma conta API Dog, faça login clicando no botão "Entrar" no canto superior direito da página. Se você não tiver uma conta, pode criar uma clicando no botão "Criar Conta" e seguindo as instruções.
Passo 3. Crie um Novo Projeto
Depois de fazer login, clique no botão "Criar Projeto" para criar um novo projeto.
Passo 4. Importar Arquivo OpenAPI
Importe um arquivo de especificação OpenAPI na página de criação do projeto. Clique no botão "Importar" para prosseguir.
Passo 5. Carregue seu Arquivo OpenAPI:
Na página de importação, você verá um campo onde pode inserir a URL do seu arquivo OpenAPI. Se você não tiver uma URL, pode carregar o arquivo do seu computador local clicando na opção "ou carregue um arquivo" e selecionando o arquivo.
Inserindo a URL do meu arquivo JSON.
Passo 6. Aguarde a Conclusão da Importação
Dependendo do tamanho e da complexidade do seu arquivo OpenAPI, o processo de importação pode levar alguns minutos.
Apidog irá automaticamente analisar o arquivo e gerar uma nova API na sua conta.
Passo 7. Configure as Configurações da Sua API
Após importar o arquivo OpenAPI, você será direcionado para a página de configurações da sua nova API. Você pode configurar diferentes definições nesta página, como o nome, descrição e requisitos de autenticação da sua API.
Passo 8. Comece a Criar Sua API
Assim que você configurar as definições da sua API, pode adicionar endpoints e documentação à sua API usando a interface intuitiva do Apidog.
Seguindo os simples passos de importar um arquivo de especificação OpenAPI no Apidog, você pode gerenciar e documentar seus projetos de API de forma mais eficiente. O arquivo de especificação normalmente inclui detalhes essenciais, como o endpoint POST, caminho, parâmetros e códigos de resposta.
Depois de adicionar seu arquivo de especificação ao Apidog, você pode aproveitar sua API amigável e ferramentas poderosas para garantir consistência e confiabilidade em seu processo de desenvolvimento de API. Portanto, se você deseja economizar tempo e simplificar seu processo de desenvolvimento de API, considere usar a Especificação OpenAPI com o Apidog.
