PDF Blocks
料金サポート
無料で始める
ページへ移動

OpenAPI 仕様

API の機械可読な OpenAPI 記述をどこで入手できるか、それが何に役立つか、そこからクライアントを生成する方法について説明します。

PDF Blocks の API は、単一の OpenAPI ドキュメントによって記述されています。これは、このドキュメントが準拠している機械可読な契約です。OpenAPI 3.0.0 に準拠しており、現在のバージョンは 1.18.0、pdfblocks.openapi.yaml として公開されています。API のすべてのルート、パラメーター、列挙値、制約、レスポンスがそこに定義されているため、型付きクライアントを生成したり、リクエストがプロセスを離れる前に検証したり、モックサーバーを立てたりできます。

公式の SDK はありません。生の HTTP が第一級の手段であり、この仕様からのコード生成が、型付きクライアントを得るサポート対象の方法です。ホスト型のダウンロード URL は準備中です。それまでは、最新の pdfblocks.openapi.yaml をsupport@pdfblocks.comまでご請求ください。

仕様が役立つ場面

  • 型付きクライアント。 マルチパートの呼び出しを手書きする代わりに、お使いの言語でモデルとリクエストメソッドを生成します。
  • 検証。 テストやサービスの入り口で、リクエストとレスポンスをスキーマと照合します。
  • モック。 実際の呼び出しを組み込む前に、ドキュメントをモックサーバーに読み込ませて開発します。
  • エディタサポート。 OpenAPI に対応したエディタに読み込ませることで、自動補完とインラインドキュメントを利用できます。

型付きクライアントを生成する

契約を pdfblocks.openapi.yaml としてローカルに保存し、コードジェネレータに渡します。OpenAPI Generator は最も多くの言語をカバーしています。以下は Python クライアントの雛形を生成する例です。

openapi-generatorbash
npm install -g @openapitools/openapi-generator-cli

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

-g python を ruby、csharp、typescript-fetch、go、php、その他サポートされている任意のジェネレータに置き換えられます。よく使われる代替手段が2つあります。

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

どのツールを使う場合でも、生成されたクライアントにはベース URL https://api.pdfblocks.com を設定し、キーは X-API-Key ヘッダーで送信してください。サポートされている統合方法の全体像については、ライブラリと連携を参照してください。

仕様とドキュメントの違い

仕様はマシンにとっての真実であり、このドキュメントは人間にとっての真実です。OpenAPI ドキュメントは、すべてのリクエストとレスポンスの正確な形を示します。文章によるドキュメントは、スキーマでは示せないもの、つまりアクションをなぜ、いつ使うのか、7つの言語による実例、透かしテンプレートのカタログ、エラーからの復旧方法を補います。両方を活用してください。生成と検証には仕様を、理解にはドキュメントを使います。

クライアントコードは特定のバージョンに対して生成されます。生成したクライアントを固定する前に、バージョニングと安定性を読み、どの変更が後方互換であるか、および破壊的変更がどのように配信されるかを確認してください。