O OpenAPI (anteriormente conhecido como Swagger) é um padrão aberto para descrever APIs RESTful de forma estruturada, legível tanto por humanos quanto por máquinas. Ele define um formato (geralmente em YAML ou JSON) que descreve todos os aspectos de uma API: seus endpoints, métodos HTTP (como GET, POST, PUT, DELETE), parâmetros de entrada, tipos de resposta, códigos de erro e até exemplos de uso.
Em outras palavras, o OpenAPI funciona como um contrato entre o back-end e o front-end (ou entre diferentes serviços). Antes mesmo de a API ser implementada, esse contrato permite que desenvolvedores saibam exatamente como interagir com o sistema, quais dados esperar e como lidar com erros.
O nome Swagger surgiu originalmente como o conjunto de ferramentas criado para trabalhar com esse padrão — e embora o padrão tenha sido renomeado para OpenAPI, o termo Swagger ainda é amplamente usado para se referir às ferramentas que o suportam, como o Swagger Editor, o Swagger UI e o Swagger Codegen.
Essas ferramentas facilitam muito o processo de desenvolvimento: o Swagger UI, por exemplo, gera automaticamente uma documentação interativa, onde é possível testar endpoints da API diretamente pelo navegador, sem precisar de outro cliente. O Swagger Codegen permite gerar código de cliente e servidor automaticamente a partir da especificação, acelerando o desenvolvimento e reduzindo inconsistências.
Um exemplo simples de documento OpenAPI seria:
openapi: 3.0.0
info:
title: API de Rastreamento de Entregas
version: 1.0.0
paths:
/entregas/{id}:
get:
summary: Retorna informações sobre uma entrega específica
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Informações da entrega
content:
application/json:
schema:
type: object
properties:
status:
type: string
data_prevista:
type: string
format: date
'404':
description: Entrega não encontrada
Code language: YAML (yaml)Esse pequeno trecho já é suficiente para gerar automaticamente uma interface de teste, gerar código para consumo da API e servir como documentação técnica.
Em resumo, o OpenAPI/Swagger transforma a documentação de APIs em algo vivo, padronizado e funcional, essencial para práticas modernas como o Document-First Development e para o desenvolvimento colaborativo entre múltiplas equipes.