PDF Blocks
PreçosSuporte
Começar grátis
Abrir a página

Especificação OpenAPI

Onde encontrar a descrição OpenAPI legível por máquina da API, para que ela serve e como gerar um cliente a partir dela.

A API do PDF Blocks é descrita por um único documento OpenAPI, o contrato legível por máquina com base no qual esta documentação é escrita. Ele é OpenAPI 3.0.0, atualmente na versão 1.18.0, publicado como pdfblocks.openapi.yaml. Toda rota, parâmetro, enumeração, restrição e resposta da API está definida ali, então você pode gerar um cliente tipado, validar requisições antes que elas saiam do seu processo ou levantar um servidor de simulação.

Não existe nenhum SDK oficial: o HTTP puro é o caminho de primeira classe, e a geração de código a partir desta especificação é a forma apoiada de obter um cliente tipado. Uma URL de download hospedada está a caminho; enquanto isso, peça o pdfblocks.openapi.yaml atual em support@pdfblocks.com.

Para que serve a especificação

  • Clientes tipados. Gere modelos e métodos de requisição na sua linguagem em vez de escrever chamadas multipart à mão.
  • Validação. Verifique requisições e respostas contra o esquema nos seus testes ou na borda do seu serviço.
  • Simulação. Entregue o documento a um servidor de simulação para desenvolver antes de ligar as chamadas reais.
  • Suporte no editor. Carregue-a em um editor que entenda OpenAPI para ter autocompletar e documentação embutida.

Gerar um cliente tipado

Salve o contrato localmente como pdfblocks.openapi.yaml e depois aponte um gerador de código para ele. O OpenAPI Generator cobre o maior número de linguagens; isto monta um cliente Python:

openapi-generatorbash
npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i pdfblocks.openapi.yaml \
  -g python \
  -o ./pdfblocks-client

Troque -g python por ruby, csharp, typescript-fetch, go, php ou qualquer outro gerador com suporte. Duas alternativas comuns:

Swagger Codegenbash
# Multi-language generator, similar to OpenAPI Generator.
swagger-codegen generate \
  -i pdfblocks.openapi.yaml \
  -l java \
  -o ./pdfblocks-client
openapi-typescriptbash
# TypeScript types only (no runtime client): pairs well with fetch.
npx openapi-typescript pdfblocks.openapi.yaml \
  --output ./pdfblocks.d.ts

Seja qual for a ferramenta, configure o cliente gerado com a URL base https://api.pdfblocks.com e envie sua chave no cabeçalho X-API-Key. Consulte Bibliotecas e integrações para o panorama completo das superfícies de integração com suporte.

Especificação vs. documentação

A especificação é a verdade da máquina; esta documentação é a verdade humana. O documento OpenAPI dá a você o formato exato de cada requisição e de cada resposta. A documentação em prosa acrescenta o que um esquema não consegue: por que e quando usar uma ação, exemplos completos em sete linguagens, o catálogo de modelos de marca-d’água e a recuperação de erros. Use os dois: a especificação para gerar e validar, a documentação para entender.

O código do cliente é gerado a partir de uma versão específica. Antes de fixar um cliente gerado, leia Versionamento e estabilidade para saber quais mudanças são retrocompatíveis e como as mudanças incompatíveis são publicadas.