# OpenAPI 仕様

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

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

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

## 仕様が役立つ場面

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

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

契約を `pdfblocks.openapi.yaml` としてローカルに保存し、コードジェネレータに渡します。[OpenAPI Generator](https://openapi-generator.tech) は最も多くの言語をカバーしています。以下は 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
```

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

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

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

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

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

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