# Specifica OpenAPI

Dove trovare la descrizione OpenAPI leggibile dalla macchina dell’API, a che cosa serve e come generarne un client.

L’API di PDF Blocks è descritta da un unico documento OpenAPI, il contratto
leggibile dalla macchina su cui è scritta questa documentazione. È **OpenAPI
3.0.0**, attualmente alla versione `1.18.0`, pubblicato come
`pdfblocks.openapi.yaml`. Ogni rotta, parametro, enumerazione, vincolo e risposta
dell’API è definito lì, quindi è possibile generare un client tipizzato,
convalidare le richieste prima che lascino il proprio processo oppure allestire
un server di mock.

<Note>
  Non esiste [alcun SDK ufficiale](/docs/api/libraries-and-integrations): l’HTTP
  grezzo è la via di prima classe e la generazione di codice a partire da questa
  specifica è il modo supportato per ottenere un client tipizzato. Un URL di
  download ospitato è in arrivo; nel frattempo, richiedere il
  `pdfblocks.openapi.yaml` attuale a
  [support@pdfblocks.com](mailto:support@pdfblocks.com).
</Note>

## A che cosa serve la specifica

- **Client tipizzati.** Generare modelli e metodi di richiesta nel proprio
  linguaggio invece di scrivere a mano le chiamate multipart.
- **Convalida.** Verificare richieste e risposte rispetto allo schema nei test o
  al confine del proprio servizio.
- **Mock.** Dare il documento a un server di mock per sviluppare prima di
  collegare chiamate reali.
- **Supporto nell’editor.** Caricarlo in un editor che conosce OpenAPI per avere
  autocompletamento e documentazione in linea.

## Generare un client tipizzato

Salvare il contratto in locale come `pdfblocks.openapi.yaml`, poi puntarci un
generatore di codice. [OpenAPI Generator](https://openapi-generator.tech) copre
il maggior numero di linguaggi; questo comando genera l’impalcatura di un client
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
```

Sostituire `-g python` con `ruby`, `csharp`, `typescript-fetch`, `go`, `php` o
qualsiasi altro generatore supportato. Due alternative comuni:

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

Qualunque strumento si usi, configurare il client generato con l’URL di base
`https://api.pdfblocks.com` e inviare la propria chiave nell’intestazione
`X-API-Key`. Vedere [Librerie e
integrazioni](/docs/api/libraries-and-integrations) per il quadro completo delle
superfici di integrazione supportate.

## Specifica e documentazione

La specifica è la verità per la macchina; questa documentazione è la verità per
la persona. Il documento OpenAPI dà la forma esatta di ogni richiesta e di ogni
risposta. La documentazione in prosa aggiunge ciò che uno schema non può dire:
*perché* e *quando* usare un’azione, esempi svolti in sette linguaggi, il
catalogo dei modelli di filigrana e il recupero dagli errori. Usare entrambe: la
specifica per generare e convalidare, la documentazione per capire.

Il codice del client viene generato a partire da una versione precisa. Prima di
fissare un client generato, leggere [Versionamento e
stabilità](/docs/api/versioning-and-stability) per sapere quali modifiche sono
retrocompatibili e come vengono rilasciate quelle incompatibili.