# 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.

<Note>
  Não existe [nenhum SDK oficial](/docs/api/libraries-and-integrations): 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](mailto:support@pdfblocks.com).
</Note>

## 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](https://openapi-generator.tech) cobre o maior número de linguagens;
isto monta um cliente Python:

```bash title="openapi-generator"
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:

<CodeGroup>

```bash title="Swagger Codegen"
# Multi-language generator, similar to OpenAPI Generator.
swagger-codegen generate \
  -i pdfblocks.openapi.yaml \
  -l java \
  -o ./pdfblocks-client
```

```bash title="openapi-typescript"
# TypeScript types only (no runtime client): pairs well with fetch.
npx openapi-typescript pdfblocks.openapi.yaml \
  --output ./pdfblocks.d.ts
```

</CodeGroup>

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](/docs/api/libraries-and-integrations) 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](/docs/api/versioning-and-stability) para saber quais mudanças são
retrocompatíveis e como as mudanças incompatíveis são publicadas.