feat: pagination with templates

[t0mk]

This PR adds logic for generating listing functions capable of going through all the pages (think devices in a project, or events in a device).

It adds templates for the new code, docs, and code tests. The templates are fetched from oag v7.0.0, and then modified for the sake of the paginated listers.

It uses vendor extension property object in the form

     x-paginated:
        x-paginated-property: Events

The spec patching part can be done in other oag generated SDKs.

related to #135

fixes #131

[t0mk]

@ctreatma

In the API specs, there are several operations that have the page etc. params, but their response schema doesn't have the meta object (where there's the page number of the resource list in response).

Namely:

• op findVirtualCircuitEvents, Response schema: Event (singular)
• op findVrfRouteEventsRequest, Response schema: Event (singular)
• op findProjectLicenses, Response schema: LicenseList

This is something that could be checked automatically when creating new api doc. In naive code:

for p in paths:
  if "Page" in p.get.params:
    assert("meta" in p.get.response.schema)

[ctreatma]

@sbhatnagar-equinix take a look at @t0mk's comment above; he has a good suggestion in there to proactively catch missing properties for paginated endpoints.

[t0mk]

@ctreatma @displague Another iteration of the pagination code generation. This time I managed to actually do a paginated call in go, using the generated code from the new template.

I updated the pytohn script to add also the property name, you can see it https://github.com/equinix-labs/metal-go/pull/150/commits/c5edb884a8736db09f8705ed161a0e346105c4a8

I updated the template so that it uses the property and so that the code actually works: https://github.com/equinix-labs/metal-go/pull/150/commits/4ddb78faf606cb2bd5742486b78799cdf1506c88 (scroll down)

Example of generated code: https://github.com/equinix-labs/metal-go/blob/pagination_with_templates/metal/v1/api_devices_paginated_listers.go

[t0mk]

Make the prefix x-equnix-metal-pagination and x-equinix-metal-paginated-property, hopefully there no limit for the property name. @ctreatma @displague

[t0mk]

@ctreatma @displague I rebased and cleaned this PR. You can see the gradual changes in the commits added today (25-09-2023). It's big but quite structured.

I didn't have to do any change to the Makefile :thinking:

This is ready for review.

[t0mk]

@displague I will include your suggestions in this PR. I will also change the property name to x-equinix-metal-paginated-property.

[t0mk]

@displague all changes done

• chanted property to x-equinix-metal-paginated-property
• changed comments to your suggestions
• regenerated everything

Please review again.

[github-actions[bot]]

This PR is included in version 0.23.0 :tada: