Paginated

A 200 response with a paginated list of items.

Table

Parameter	Type	Description
status	integer	The HTTP status code
message	string	The message to return
items	array	Items from the current page
paginationInfo	PaginationInfo	Details about the pagination

Formats

Example

An example paginated response:

{
  "status": 200,
  "message": "Success",
  "items": [
    {
      "id": "123",
      "name": "Test 1"
    },
    {
      "id": "124",
      "name": "Test 2"
    }
  ],
  "paginationInfo": {
    "page": 1,
    "pageSize": 10,
    "totalItems": 25,
    "totalPages": 3
  }
}

JSON Schema

The JSON schema for this model is:

$schema: https://json-schema.org/draft/2020-12/schema
$id: Paginated.yaml
type: object
properties:
  status:
    type: integer
    minimum: 200
    default: 200
    description: The HTTP status code
  message:
    type: string
    default: "Success"
    description: The message to return
  items:
    type: array
    description: Items from the current page
  paginationInfo:
    $ref: "#/components/schemas/CommonGrants.Pagination.PaginationInfo"
required:
  - status
  - message
  - items
  - paginationInfo

TypeSpec

The TypeSpec code for this model is:

/** Template for a 200 response with paginated list of items
 *
 * @template T The schema for the value of the `"items"` property in this response
 */
@doc("A 200 response with a paginated list of items")
model Paginated<T> extends Success {
  // Inherit the 200 status code
  ...Http.OkResponse;

  /** Items from the current page */
  @pageItems
  items: T[];

  /** Details about the paginated results */
  paginationInfo: Pagination.PaginationInfo;
}

OpenAPI

The OpenAPI specification for this model is:

components:
  schemas:
    CommonGrants.Responses.Paginated:
      type: object
      properties:
        status:
          type: integer
          minimum: 200
          default: 200
          description: The HTTP status code
        message:
          type: string
          default: "Success"
          description: The message to return
        items:
          type: array
          description: Items from the current page
        paginationInfo:
          $ref: "#/components/schemas/CommonGrants.Pagination.PaginationInfo"
      required:
        - status
        - message
        - items
        - paginationInfo

Usage

Here’s an example of how to use the Paginated response within a an API operation:

import "@common-grants/core";
import "@typespec/http";

using TypeSpec.Http;
using CommonGrants.Pagination;
using CommonGrants.Responses;

model TestModel {
  id: string;
  name: string;
}

@summary("List test models")
@doc("Get a paginated list of test models")
@get
op listTest(...PaginatedQueryParams): Paginated<TestModel>;