メインコンテンツまでスキップ
バージョン: 0.9.0 (最新)

📄 ページネーションスキーマ

ページネーションスキーマは、Nodeblocksアプリケーション全体で標準化されたページネーションパラメータとメタデータ用のJSONスキーマ定義を提供します。これらのスキーマは、一貫したページネーション動作とレスポンスフォーマットを保証します。

🎯 概要​

ページネーションスキーマは以下の目的で設計されています：

  • すべてのAPIエンドポイントでのページネーションの標準化
  • 適切な制約によるページネーションパラメータの検証
  • レスポンスでの一貫したページネーションメタデータの保証
  • 共通操作用の再利用可能な文字列配列のサポート
  • エンティティ固有のスキーマとの合成の実現

📋 ページネーションスキーマタイプ​

クエリパラメータスキーマ​

APIリクエストで使用されるページネーションクエリパラメータ用のスキーマ。

レスポンスメタデータスキーマ​

APIレスポンスに含まれるページネーションメタデータ用のスキーマ。

ユーティリティスキーマ​

ページネーション関連の共通操作用の再利用可能なスキーマ。

🔧 利用可能なページネーションスキーマ​

paginationQueryParametersSchema​

APIエンドポイント全体で標準化されたページネーション用のページネーションクエリパラメータスキーマ。

目的: リスト/検索エンドポイント用の一貫したページネーションパラメータを提供します

スキーマ詳細:

  • Type: OpenAPIParameter[]
  • Parameters:
    • page?: number (1-1000, オプション) - ページネーション用のページ番号
    • limit?: number (1-50, オプション) - ページあたりのレコード数

使用例:

import { schemas } from '@nodeblocks/backend-sdk';

const { paginationQueryParametersSchema } = schemas;

const schema = withSchema({
  parameters: [
    ...paginationQueryParametersSchema,
    // other parameters
  ]
});
// Used in: GET /identities?page=1&limit=10

paginationSchema​

ページネーションされたレスポンス情報用のページネーションメタデータスキーマ。

目的: APIレスポンスのページネーションメタデータを検証します

スキーマ詳細:

  • Type: object
  • Required Fields: page, limit, total, total_pages
  • Additional Properties: false（厳密な検証）
  • Properties:
    • page: number - 現在のページ番号（最小値: 1）
    • limit: number - ページあたりのレコード数（最小値: 1）
    • total: number - レコードの総数（最小値: 0）
    • total_pages: number - ページの総数（最小値: 0）

使用例:

import { schemas } from '@nodeblocks/backend-sdk';

const { paginationSchema } = schemas;

const validate = ajv.compile(paginationSchema.schemas as SchemaDefinition);
const isValid = validate({
  page: 1,
  limit: 10,
  total: 100,
  total_pages: 10
});

arrayOfStringsSchema​

再利用可能な文字列配列検証用の文字列配列スキーマ定義。

目的: 文字列値のみを含む配列を検証します

スキーマ詳細:

  • Type: array
  • Items: string
  • Additional Properties: false（厳密な検証）

使用例:

import { schemas } from '@nodeblocks/backend-sdk';

const { arrayOfStringsSchema } = schemas;

const validate = ajv.compile(arrayOfStringsSchema);
const isValid = validate(['item1', 'item2', 'item3']);