feat: pagination with templates (#150)

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
```yaml
     x-paginated:
        x-paginated-property: Events
```

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

related to #135 

fixes #131

---------

Signed-off-by: Tomáš Karásek <t0mk@users.noreply.github.com>
Co-authored-by: Marques Johansson <mjohansson@equinix.com>

api/openapi.yaml

@@ -1094,6 +1094,7 @@ paths:
       summary: Retrieve interconnection events
       tags:
       - Events
+      x-equinix-metal-paginated-property: Events
   /connections/{connection_id}/ports:
     get:
       description: List the ports associated to an interconnection.
@@ -2018,6 +2019,7 @@ paths:
       summary: Retrieve device's events
       tags:
       - Events
+      x-equinix-metal-paginated-property: Events
   /devices/{id}/firmware-sets:
     get:
       description: "Returns the firmware set associated with the device. If a custom\
@@ -2678,6 +2680,7 @@ paths:
       summary: Retrieve current user's events
       tags:
       - Events
+      x-equinix-metal-paginated-property: Events
   /events/{id}:
     get:
       description: Returns a single event if the user has access
@@ -4543,6 +4546,7 @@ paths:
       summary: Retrieve all organizations
       tags:
       - Organizations
+      x-equinix-metal-paginated-property: Organizations
     post:
       description: Creates an organization.
       operationId: createOrganization
@@ -5044,6 +5048,7 @@ paths:
       summary: Retrieve all devices of an organization
       tags:
       - Devices
+      x-equinix-metal-paginated-property: Devices
   /organizations/{id}/events:
     get:
       description: Returns a list of events for a single organization
@@ -5126,6 +5131,7 @@ paths:
       summary: Retrieve organization's events
       tags:
       - Events
+      x-equinix-metal-paginated-property: Events
   /organizations/{id}/facilities:
     get:
       deprecated: true
@@ -5729,6 +5735,7 @@ paths:
       summary: Retrieve all projects of an organization
       tags:
       - Organizations
+      x-equinix-metal-paginated-property: Projects
     post:
       description: Creates a new project for the organization
       operationId: createOrganizationProject
@@ -7042,6 +7049,7 @@ paths:
       summary: Retrieve all projects
       tags:
       - Projects
+      x-equinix-metal-paginated-property: Projects
     post:
       description: "Creates a new project for the user default organization. If the\
         \ user don't have an organization, a new one will be created."
@@ -7750,6 +7758,7 @@ paths:
       summary: Retrieve all devices of a project
       tags:
       - Devices
+      x-equinix-metal-paginated-property: Devices
     post:
       description: |-
         Creates a new device and provisions it in the specified location.
@@ -7964,6 +7973,7 @@ paths:
       summary: Retrieve project's events
       tags:
       - Events
+      x-equinix-metal-paginated-property: Events
   /projects/{id}/facilities:
     get:
       deprecated: true
@@ -8211,6 +8221,7 @@ paths:
       summary: Retrieve all hardware reservations for a given project
       tags:
       - HardwareReservations
+      x-equinix-metal-paginated-property: HardwareReservations
   /projects/{id}/ips:
     get:
       description: Provides a paginated list of IP reservations for a single project.
@@ -9253,6 +9264,7 @@ paths:
       summary: List project connections
       tags:
       - Interconnections
+      x-equinix-metal-paginated-property: Interconnections
     post:
       description: Creates a new interconnection request
       operationId: createProjectInterconnection
@@ -9636,6 +9648,7 @@ paths:
       summary: Returns all metal gateways for a project
       tags:
       - MetalGateways
+      x-equinix-metal-paginated-property: MetalGateways
     post:
       description: Create a metal gateway in a project
       operationId: createMetalGateway
@@ -11204,6 +11217,7 @@ paths:
       summary: Retrieve all users
       tags:
       - Users
+      x-equinix-metal-paginated-property: Users
     post:
       description: Creates a user.
       operationId: createUser

docs/DevicesApi.md

@@ -901,6 +901,7 @@ Name | Type | Description  | Notes
 Retrieve all devices of an organization
 
 
+FindOrganizationDevices is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 
@@ -995,6 +996,7 @@ Name | Type | Description  | Notes
 Retrieve all devices of a project
 
 
+FindProjectDevices is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 

docs/EventsApi.md

@@ -23,6 +23,7 @@ Method | HTTP request | Description
 Retrieve device's events
 
 
+FindDeviceEvents is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 
@@ -175,6 +176,7 @@ Name | Type | Description  | Notes
 Retrieve current user's events
 
 
+FindEvents is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 
@@ -247,6 +249,7 @@ Name | Type | Description  | Notes
 Retrieve interconnection events
 
 
+FindInterconnectionEvents is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 
@@ -406,6 +409,7 @@ Name | Type | Description  | Notes
 Retrieve organization's events
 
 
+FindOrganizationEvents is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 
@@ -484,6 +488,7 @@ Name | Type | Description  | Notes
 Retrieve project's events
 
 
+FindProjectEvents is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 

docs/HardwareReservationsApi.md

@@ -168,6 +168,7 @@ Name | Type | Description  | Notes
 Retrieve all hardware reservations for a given project
 
 
+FindProjectHardwareReservations is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 

docs/InterconnectionsApi.md

@@ -920,6 +920,7 @@ Name | Type | Description  | Notes
 List project connections
 
 
+ProjectListInterconnections is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 

docs/MetalGatewaysApi.md

@@ -324,6 +324,7 @@ Name | Type | Description  | Notes
 Returns all metal gateways for a project
 
 
+FindMetalGatewaysByProject is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 

docs/OrganizationsApi.md

@@ -757,6 +757,7 @@ Name | Type | Description  | Notes
 Retrieve all projects of an organization
 
 
+FindOrganizationProjects is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 
@@ -909,6 +910,7 @@ Name | Type | Description  | Notes
 Retrieve all organizations
 
 
+FindOrganizations is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 

docs/ProjectsApi.md

@@ -678,6 +678,7 @@ Name | Type | Description  | Notes
 Retrieve all projects
 
 
+FindProjects is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example
 

docs/UsersApi.md

@@ -371,6 +371,7 @@ Name | Type | Description  | Notes
 Retrieve all users
 
 
+FindUsers is a paginated API operation. You can specify page number and per page parameters with `Execute`, or to fetch and return all pages of results as a single slice you can call `ExecuteWithPagination()`. `ExecuteWithPagination()`, while convenient, can significantly increase the overhead of API calls in terms of time, network utilization, and memory. Excludes can make the call more efficient by removing any unneeded nested fields that are included by default. If any of the requests fail, the list of results will be nil and the error returned will represent the failed request.
 
 ### Example