A especificação OpenAPI da nossa API: o que é, onde a descarregar e o que contém

A resposta curta: a especificação OpenAPI é um ficheiro JSON, openapi.json, que descreve toda a API num formato que as ferramentas entendem: o endereço, cada operação, os parâmetros, os corpos dos pedidos, as respostas, os erros e a forma de autenticar. A Referência da documentação nasce deste mesmo ficheiro. Está no formato OpenAPI 3.1.

Onde está

Onde	Como lá chegar
Na Referência da API	No fim da página, na secção Especificação: Descarregar a especificação OpenAPI. Traz já o endereço da API da MozOut.
No llms.txt	Na última secção, Specification.
Na própria API	A operação GET /v1/openapi.json devolve a especificação, sem chave.

Para importar numa ferramenta, use o ficheiro da Referência, que é o que acompanha a documentação que está a ler.

O que tem lá dentro

Parte	O que é
info	O nome, a versão e a descrição: como autenticar e o que distingue os modos Sandbox e Produção.
servers	O endereço base da API.
paths	Cada operação, com o resumo, os parâmetros, o corpo, as respostas e exemplos.
components	As peças repetidas: esquemas dos dados, respostas de erro, cabeçalhos e a autenticação bearerAuth, a chave no cabeçalho Authorization.
tags	As áreas: domains, dns, sms, billing e as outras. As ferramentas usam-nas para fazer pastas.
Campos x-	Extensões nossas: x-permission diz a permissão de cada operação, x-summary-pt e x-description-pt trazem os textos em português, e x-limits resume os limites.

Para que serve

1	Importar num cliente de API, como o Postman ou o Insomnia, e ter todos os pedidos prontos: veja o Postman e o Insomnia e outros clientes.

2	Gerar um cliente na sua linguagem: veja gerar um cliente da API.

3	Validar nos seus testes que os pedidos e as respostas do seu programa batem com o que a API espera.

4	Dar a um assistente de IA a descrição exacta das operações.

5	Ver o que mudou: guarde uma cópia e compare-a com a seguinte.

Os textos normais da especificação estão em inglês. Os portugueses estão nos campos x-summary-pt e x-description-pt, que a maioria das ferramentas ignora. É normal ver os nomes das operações em inglês depois de importar.

Os caminhos começam por /v1 e o endereço do servidor não o leva. Se configurar uma ferramenta à mão, não junte o /v1 duas vezes.

Descarregue a especificação e importe-a na sua ferramenta preferida.

Descarregar a especificação

VEJA TAMBÉM

Importar a nossa API no Postman a partir da especificação OpenAPI, passo a passo

Importar a nossa API no Insomnia e noutros clientes de API, e configurar a chave Bearer

Gerar um cliente da API para a sua linguagem a partir da nossa especificação OpenAPI

A documentação da API e a IA: o ficheiro llms.txt e dar a documentação inteira a um assistente

Como está organizada a documentação da API: Começar, Áreas, Referência e Playground

PRODUTO RECOMENDADO

Alojamento de sites com cPanel

Domínio e SSL incluídos, cópias diárias e o painel que já conhece. desde 5,94 €/mês (plano de 3 anos, com cupão)

Ver planos

Categorias

Categorias