PDF Blocks
PreiseSupport
Kostenlos starten
Seite öffnen

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.

Es gibt kein offizielles SDK: 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 an.

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 deckt die meisten Sprachen ab; das Folgende erzeugt das Gerüst eines Python-Clients:

openapi-generatorbash
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:

Swagger Codegenbash
# Multi-language generator, similar to OpenAPI Generator.
swagger-codegen generate \
  -i pdfblocks.openapi.yaml \
  -l java \
  -o ./pdfblocks-client
openapi-typescriptbash
# TypeScript types only (no runtime client): pairs well with fetch.
npx openapi-typescript pdfblocks.openapi.yaml \
  --output ./pdfblocks.d.ts

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.

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, um zu wissen, welche Änderungen abwärtskompatibel sind und wie inkompatible Änderungen ausgeliefert werden.