Api 408/cursor pagination

[cjea]

Add cursor pagination to Reslang (Jira)

Description

The MULTIGET operation takes an optional pagination block, which corresponds to the _pagination response in our standards.

If no pagination block is provided, then Reslang defaults to using cursor pagination, with a cursor field called after. This:

/operations
  MULTIGET

is equivalent to

/operations
  MULTIGET pagination {
    after = true
    defaultLimit = <the default limit from rules.json>
    maxLimit = <the maximum limit from rules.json>
}

If you do specify a pagination block, then it can be configured with some pre-determined officially supported fields. All of the valid fields are:

/operations
        MULTIGET pagination {
            defaultLimit = 10
            maxLimit  = 100
            after     = true
            before    = true
            total     = true
            next      = true
            previous  = true
        }

limit is always added as a query parameter to paginated calls (default values specified in rules.json if it's not specified by the user). If after and/or before are included, then Reslang will automatically inject them into the swagger spec as query params as well.

Values for pagination fields can only be booleans, or numbers (in the case of defaultLimit and maxLimit). Anything else will cause an error, but this can also be updated easily in the future if need be. If a field is set to false, then it's equivalent to not including it at all, but it can be helpful as a "TODO"-style reminder.

This code should ideally make it very easy to get swagger specs whose pagination complies with our standards. Only valid fields are supported in the pagination block, and other fields are ignored with a warning. For example, given this pagination block:

MULTIGET pagination { foo = true }

Reslang generation will still work with that configuration, but it will output the following warning:

unrecognized pagination option: foo

We don't want devs putting arbitrary fields in the pagination response (which enables typos, or "custom" pagination strategies...), so I'm hoping that warning + ignoring is a good user experience, as opposed to simply allowing everything, or throwing.

Legacy

For APIs that still use offset+limit pagination, they can use the following keyword:

/operations
  MULTIGET deprecated-offset-pagination

That will hardcode the limit/offset query params, as well as include the (now-deprecated) X-Total-Count header in swagger responses.

[ops-github-DU4JOAWE]

This change is 

[JacobCrofts]

Wow, go CJ! 🎉