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

A resposta curta: um gerador de clientes lê a nossa especificação OpenAPI e escreve o código que chama a API na sua linguagem, com uma função para cada operação. Poupa trabalho quando usa muitas operações. O mais conhecido é o OpenAPI Generator, que gera clientes para PHP, Python, TypeScript, Java, C#, Go e muitas outras.

Com o OpenAPI Generator

1	Descarregue a especificação para a pasta do projecto, com o nome openapi.json.

2	Tenha o gerador disponível: a versão de linha de comandos pelo npm precisa de Java instalado; em alternativa, corre em Docker sem instalar mais nada.

3	Gere o cliente na linguagem que quer, com um destes comandos:

4	Configure o cliente gerado com o endereço da API e a chave Bearer, lida da variável RLX_API_KEY, como nos exemplos da documentação.

npx @openapitools/openapi-generator-cli generate -i openapi.json -g python -o cliente-python
npx @openapitools/openapi-generator-cli generate -i openapi.json -g php -o cliente-php
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate -i /local/openapi.json -g typescript-fetch -o /local/cliente-ts

Linguagem	Valor de -g
PHP	php
Python	python
TypeScript ou JavaScript	typescript-fetch ou javascript
Java	java
C#	csharp
Go	go

Antes de confiar no código gerado

O gerador conhece a forma da API, não as regras. Ele não sabe que deve enviar Idempotency-Key nas compras e nos pagamentos, que deve esperar o Retry-After depois de um 429, nem que as listas vêm em páginas. Isso está nas Regras da API e tem de o acrescentar.

1	Use uma versão recente do gerador. O suporte ao OpenAPI 3.1 é mais recente do que ao 3.0 e melhora de versão para versão.

2	Teste tudo com uma chave sandbox_ antes de passar para prod_.

3	Volte a gerar quando a especificação mudar, e não edite à mão os ficheiros gerados: as alterações perdem-se na geração seguinte.

Gerar ou escrever à mão?

Situação	O que compensa
Usa duas ou três operações	Escrever à mão, a partir dos exemplos da documentação: menos código, menos dependências.
Usa muitas operações, de várias áreas	Gerar o cliente e escrever por cima uma camada sua com as regras da API.
Tem uma equipa a trabalhar na integração	Gerar, para todos usarem os mesmos nomes e tipos.

Quer só experimentar sem código? O Playground e os clientes de API fazem os mesmos pedidos: veja o Postman.

Comece por descarregar a especificação.

Descarregar a especificação

VEJA TAMBÉM

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

Exemplos de código na documentação da API: curl, PHP, Python e JavaScript, prontos a adaptar

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

Chamar uma API web a partir do PHP com o cURL e ler a resposta em JSON

PRODUTO RECOMENDADO

Hospedagem de sites com cPanel

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

Ver planos

Categorias

Categorias