# OpenAPI-Spezifikation

Wo Sie die maschinenlesbare OpenAPI-Beschreibung der API finden, wofür sie gut ist und wie Sie daraus einen Client generieren.

Die API von PDF Blocks wird durch ein einziges OpenAPI-Dokument beschrieben:
den maschinenlesbaren Vertrag, gegen den diese Dokumentation geschrieben ist.
Es ist **OpenAPI 3.0.0**, derzeit in Version `1.18.0`, veröffentlicht als
`pdfblocks.openapi.yaml`. Jede Route, jeder Parameter, jede Aufzählung, jede
Einschränkung und jede Antwort der API ist dort definiert. So können Sie einen
typisierten Client generieren, Anfragen validieren, bevor sie Ihren Prozess
verlassen, oder einen Mock-Server aufsetzen.

<Note>
  Es gibt [kein offizielles SDK](/docs/api/libraries-and-integrations): Rohes
  HTTP ist der erstklassige Weg, und die Codegenerierung aus dieser
  Spezifikation ist der unterstützte Weg zu einem typisierten Client. Eine
  gehostete Download-URL ist in Arbeit; fordern Sie bis dahin die aktuelle
  `pdfblocks.openapi.yaml` unter
  [support@pdfblocks.com](mailto:support@pdfblocks.com) an.
</Note>

## Wofür die Spezifikation gut ist

- **Typisierte Clients.** Generieren Sie Modelle und Anfragemethoden in Ihrer
  Sprache, statt Multipart-Aufrufe von Hand zu schreiben.
- **Validierung.** Prüfen Sie Anfragen und Antworten gegen das Schema, in Tests
  oder am Rand Ihres Dienstes.
- **Mocking.** Geben Sie das Dokument an einen Mock-Server, um dagegen zu
  entwickeln, bevor Sie echte Aufrufe verdrahten.
- **Editor-Unterstützung.** Laden Sie es in einen OpenAPI-fähigen Editor, um
  Autovervollständigung und eingebettete Dokumentation zu erhalten.

## Einen typisierten Client generieren

Speichern Sie den Vertrag lokal als `pdfblocks.openapi.yaml` und richten Sie
dann einen Codegenerator darauf.
[OpenAPI Generator](https://openapi-generator.tech) deckt die meisten Sprachen
ab; das Folgende erzeugt das Gerüst eines Python-Clients:

```bash title="openapi-generator"
npm install -g @openapitools/openapi-generator-cli

openapi-generator-cli generate \
  -i pdfblocks.openapi.yaml \
  -g python \
  -o ./pdfblocks-client
```

Tauschen Sie `-g python` gegen `ruby`, `csharp`, `typescript-fetch`, `go`,
`php` oder einen beliebigen anderen unterstützten Generator. Zwei verbreitete
Alternativen:

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

Welches Werkzeug Sie auch verwenden: Konfigurieren Sie den generierten Client
mit der Basis-URL `https://api.pdfblocks.com` und senden Sie Ihren Schlüssel im
Header `X-API-Key`. Den vollständigen Überblick über die unterstützten
Integrationsflächen finden Sie unter
[Bibliotheken und Integrationen](/docs/api/libraries-and-integrations).

## Spezifikation und Dokumentation

Die Spezifikation ist die Wahrheit für die Maschine, diese Dokumentation die
Wahrheit für den Menschen. Das OpenAPI-Dokument gibt Ihnen die genaue Form
jeder Anfrage und jeder Antwort. Die Dokumentation in Prosa ergänzt, was ein
Schema nicht kann: das *Warum* und das *Wann* einer Aktion, ausgearbeitete
Beispiele in sieben Sprachen, den Katalog der Wasserzeichenvorlagen und den
Umgang mit Fehlern. Nutzen Sie beides: die Spezifikation zum Generieren und
Validieren, die Dokumentation zum Verstehen.

Client-Code wird gegen eine bestimmte Version generiert. Bevor Sie einen
generierten Client festschreiben, lesen Sie
[Versionierung und Stabilität](/docs/api/versioning-and-stability), um zu
wissen, welche Änderungen abwärtskompatibel sind und wie inkompatible
Änderungen ausgeliefert werden.