Implementing pagination in Swagger definition for REST APIs

Question

I want to implement pagination in my REST API response. And for the DTOs and controller, I am using Swagger to generate. How can I specify that I need pagination for one particular object.

And for pagination, do I need to call the API again and again (for each page request)? Will it not be too heavy on the system as API will be performing other functions as well (which includes DB access and storage)?

Answer 1

You can define parameters to define start index and page length. The response should include total records and the no. of records currently displayed.

Here is an example -

/orders:
    get:
      tags:
        - orders
      summary: Get details about the customer orders
      description: ''
      operationId: getOrders
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: customerid
          in: query
          description: Id of the customer 
          required: true
          type: string
          collectionFormat: multi
        - name: ordered
          in: query
          description: orderid for the order  
          required: false
          type: string
          collectionFormat: multi
        - $ref: "#/parameters/Startindex"
        - $ref: "#/parameters/Pagelength"
      responses:
        200:
          description: An array of customer orders
          schema:
             type: object
             allOf:
               - $ref: '#/definitions/PaginationResponse'
               - properties:
                   devices:
                     type: array
                     items:
                       $ref: '#/definitions/Order’
        '400':
          description: Invalid ID supplied
        '404':
          description: Customer not found
        '405':
          description: Validation exception


definitions:
……
…..
 PaginationResponse:
    type: object
    properties:
      totalrecords:
        type: number
      displayrecords:
         type: number
    xml:
       name: PaginationResponsedata


parameters:
    Pagelength:
      name: pagelength
      in: query
      description: Number of records to return
      type: number
    Startindex:
      name: startindex
      in: query
      description: Start index for paging
      type: number