OpenAPI
OpenAPI (OpenAPI Specification, OAS) é o padrão aberto para descrever uma API HTTP de forma legível por máquinas: quais caminhos e métodos um serviço tem, que parâmetros eles aceitam, o que devolvem e como passar a chave. O documento é escrito em JSON ou YAML, e tanto pessoas quanto programas conseguem entender a API a partir dele, sem acesso ao código-fonte.
De onde veio o padrão
O padrão nasceu da Swagger Specification, lançada pela primeira vez em 2011. Em 2015, o Swagger 2.0 foi doado à OpenAPI Initiative, um projeto aberto da Linux Foundation, e desde 2016 a especificação é desenvolvida como OpenAPI. A versão 3.0 saiu em 2017 e a 3.1 em fevereiro de 2021; a linha mais recente é a 3.2 (a especificação 3.1).
O que o documento descreve
servers— a URL base da API;paths— caminhos e métodos: cada operação tem seuoperationId, umsummarycurto, parâmetros com sua localização (in: query, path, header) e respostas por código de status;components.schemas— schemas de objetos (na 3.1, baseados em JSON Schema 2020-12);components.securitySchemes— autenticação, por exemplo uma chave num cabeçalho:type: apiKey,in: header.
Um trecho resumido da spec da Genesis API, a operação de taxas de funding e o esquema da chave:
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/funding/rates": {
"get": {
"operationId": "getFundingRates",
"summary": "Funding rates",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query", "required": false,
"schema": { "type": "string" } }
]
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": { "type": "apiKey", "in": "header",
"name": "X-API-Key" }
}
}
}
Campos com prefixo x- são extensões da especificação: x-genesis-plans lista os planos que incluem a operação.
Para que serve uma spec
Entre seus usos, o padrão cita geração de documentação, geração de clientes e servidores em várias linguagens e testes. Para agentes de IA, uma spec é um conjunto de ferramentas pronto: uma operação com operationId, descrição e schema de parâmetros vira uma ferramenta para function calling ou um servidor MCP.
OpenAPI na Genesis API
A spec da Genesis API fica em genesisarbitrage.com/openapi.json: OpenAPI 3.1, 37 operações, a chave no cabeçalho X-API-Key (autenticação). Ela também pode ser descoberta automaticamente: o arquivo /.well-known/api-catalog de genesisarbitrage.com, definido pela RFC 9727, aponta para ela com um link service-desc. Como conectar a spec a um agente está em Genesis API para agentes de IA.
Veja também: REST API, JSON, endpoint de API, dados de mercado cripto para agentes de IA.
Perguntas e respostas
Swagger e OpenAPI são a mesma coisa?
São um único padrão com dois nomes: a Swagger Specification é desenvolvida como OpenAPI desde 2016. A versão 2.0 ainda saiu como Swagger 2.0, e a partir da 3.0 é publicada como OpenAPI Specification.
Preciso de um SDK se existe uma spec?
Não para a Genesis API: cada requisição é um GET com um único cabeçalho, então qualquer cliente HTTP serve. Gerar um cliente a partir da spec faz sentido se você quer métodos tipados.