# Spécification OpenAPI Où trouver la description OpenAPI lisible par une machine de l’API, à quoi elle sert et comment en générer un client. L’API PDF Blocks est décrite par un seul document OpenAPI, le contrat lisible par une machine sur lequel cette documentation est écrite. Il s’agit d’**OpenAPI 3.0.0**, actuellement en version `1.18.0`, publié sous le nom `pdfblocks.openapi.yaml`. Chaque route, paramètre, énumération, contrainte et réponse de l’API y est défini, ce qui vous permet de générer un client typé, de valider les requêtes avant qu’elles ne quittent votre processus, ou de monter un serveur de simulation. <Note> Il n’existe [pas de SDK officiel](/docs/api/libraries-and-integrations) : le HTTP brut est la voie de premier rang, et la génération de code depuis cette spécification est la façon prise en charge d’obtenir un client typé. Une URL de téléchargement hébergée est en préparation ; en attendant, demandez le `pdfblocks.openapi.yaml` actuel à [support@pdfblocks.com](mailto:support@pdfblocks.com). </Note> ## À quoi sert la spécification - **Clients typés.** Générez des modèles et des méthodes de requête dans votre langage au lieu d’écrire des appels multipart à la main. - **Validation.** Vérifiez les requêtes et les réponses par rapport au schéma, dans vos tests ou en bordure de votre service. - **Simulation.** Donnez le document à un serveur de simulation pour développer avant de câbler de vrais appels. - **Prise en charge par l’éditeur.** Chargez-le dans un éditeur qui connaît OpenAPI pour bénéficier de l’autocomplétion et de la documentation intégrée. ## Générer un client typé Enregistrez le contrat en local sous `pdfblocks.openapi.yaml`, puis pointez un générateur de code dessus. [OpenAPI Generator](https://openapi-generator.tech) couvre le plus grand nombre de langages ; voici de quoi échafauder 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 ``` Remplacez `-g python` par `ruby`, `csharp`, `typescript-fetch`, `go`, `php`, ou n’importe quel autre générateur pris en charge. Deux solutions de rechange courantes : <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> Quel que soit l’outil, configurez le client généré avec l’URL de base `https://api.pdfblocks.com` et envoyez votre clé dans l’en-tête `X-API-Key`. Voir [Bibliothèques et intégrations](/docs/api/libraries-and-integrations) pour le panorama complet des surfaces d’intégration prises en charge. ## Spécification et documentation La spécification est la vérité pour la machine ; cette documentation est la vérité pour l’humain. Le document OpenAPI vous donne la forme exacte de chaque requête et de chaque réponse. La documentation en prose ajoute ce qu’un schéma ne peut pas dire : *pourquoi* et *quand* utiliser une action, des exemples travaillés en sept langages, le catalogue de modèles de filigrane et la reprise sur erreur. Servez-vous des deux, la spécification pour générer et valider, la documentation pour comprendre. Le code client est généré à partir d’une version précise. Avant d’épingler un client généré, lisez [Versionnage et stabilité](/docs/api/versioning-and-stability) pour savoir quels changements sont rétrocompatibles et comment les changements incompatibles sont livrés.