メインコンテンツへスキップ
バージョン: 最新版

Schema API

Schema APIは、Omise APIのOpenAPI仕様へのアクセスを提供します。これにより、利用可能なエンドポイントをプログラムで検出し、リクエスト/レスポンス構造を理解し、APIドキュメントツールと統合できます。

概要​

Schema APIが提供するもの:

  • OpenAPI仕様 - OpenAPI 3.0形式の完全なAPIドキュメント
  • エンドポイント検出 - すべての利用可能なAPIエンドポイントをプログラムで検出
  • データ構造 - すべてのリクエストおよびレスポンスオブジェクトの完全なスキーマ定義
  • バリデーション - スキーマを使用して送信前にAPIリクエストを検証
  • コード生成 - OpenAPIコードジェネレーターを使用してクライアントライブラリを生成

Schema APIの仕組み​

  1. スキーマをリクエスト - OpenAPI仕様を取得するためにGETリクエストを実行
  2. レスポンスを解析 - レスポンスはJSON形式の完全なOpenAPI 3.0ドキュメント
  3. スキーマを使用 - Swagger UI、Postman、またはコードジェネレーターなどのツールにインポート
  4. 最新状態を維持 - スキーマはAPIの現在の状態を反映

ユースケース​

APIドキュメント​

Swagger UIやReDocなどのツールを使用してインタラクティブなAPIドキュメントを生成します。

クライアント生成​

OpenAPIコードジェネレーターを使用して、お好みの言語で型安全なクライアントライブラリを作成します。

リクエストバリデーション​

送信前にスキーマに対してAPIリクエストを検証し、エラーを早期に発見します。

IDE統合​

スキーマをIDEにインポートして、オートコンプリートと型チェックを有効にします。

APIテスト​

スキーマ定義に基づいてテストケースを生成します。

利用可能なエンドポイント​

スキーマ形式​

スキーマはOpenAPI 3.0形式で提供され、以下が含まれます:

パス​

すべての利用可能なAPIエンドポイント:

  • HTTPメソッド（GET、POST、PATCH、DELETE）
  • リクエストパラメータ（パス、クエリ、ボディ）
  • 各ステータスコードのレスポンス構造
  • 認証要件

コンポーネント​

再利用可能なスキーマ定義:

  • リクエストボディ
  • レスポンスオブジェクト
  • 共通パラメータ
  • セキュリティスキーム

セキュリティ​

認証要件:

  • APIキーを使用したHTTP Basic Auth
  • パブリックキーとシークレットキーの要件

統合例​

Swagger UI​

<script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
  SwaggerUIBundle({
    url: "https://api.omise.co/schema",
    dom_id: '#swagger-ui'
  });
</script>

Postman​

  1. Postmanを開く
  2. Importをクリック
  3. URLを入力: https://api.omise.co/schema
  4. OpenAPI 3.0としてインポート

OpenAPI Generator​

# Pythonクライアントを生成
openapi-generator generate \
  -i https://api.omise.co/schema \
  -g python \
  -o ./omise-python-client

ベストプラクティス​

推奨事項​

  • スキーマをキャッシュ - スキーマは頻繁に変更されないため、ローカルにキャッシュ
  • 統合のバージョン管理 - 利用可能な場合は特定のスキーマバージョンに固定
  • 早期検証 - API呼び出し前にエラーを発見するためにスキーマ検証を使用
  • クライアントを生成 - 型安全性と生産性のためにコードジェネレーターを使用
  • ツールを最新に保つ - OpenAPIツールが最新の仕様をサポートしていることを確認

非推奨事項​

  • 構造をハードコードしない - 動的統合にはスキーマを使用
  • 更新を無視しない - スキーマの更新を定期的にチェック
  • バリデーションをスキップしない - 開発中は常にスキーマに対して検証

関連リソース​

お困りですか？ support@omise.coまでお問い合わせください