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