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