feat: add functions to automatically navigate device pages

[ctreatma]

This serves as an example of how we could implement automatic page navigation, similar to what was done in packngo.

Relates to #131

[displague]

If we were to maintain local copies of the Go templates, we could update the template files whenever we update the OpenAPITools version via the meta CLI command which dumps the templates. In that case, is this where we would patch in a generic (mustache) version of the paginated executor:

https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/go/api.mustache#L77-L79

We would need a mustache way to identify if pagination is supported in the resource, preferably without needing to modify the Java defined attributes.

[displague]

Finding a generic approach will be helpful for templating our generated Go pattern across Fabric, NE, and future Go SDKs.

[displague]

For Metal, if this is safe for unpaginated endpoints, perhaps we can always include ExecuteWithPagination and it will degrade to a less efficient Execute:

if page.Meta.GetLastPage() <= page.Meta.GetCurrentPage() {

[displague]

type Paginated interface {
  GetCurrentPage() int32
  GetLastPage() int32
}

type WithMeta interface {
  HasMeta() bool // may just need this, if it exists
  GetMeta() something // otherwise this
}
...
if meta, ok := page.Meta.(Paginated); meta != nil && ok { 
  // ^ check meta first? does meta always exist? nil? A WithMeta Interface check could be used if this simple check wouldn't suffice
}

[displague]

This is a significant patch context. Chasing func (r ApiFindOrganizationDevicesRequest) Execute() will keep our patches applying safely. 👍

[t0mk]

@displague @ctreatma
I have tried to implement pagination with the mustache templates of openapi generator today. there are several issues:

• Mustache is logic-less, so it's hard to implement the condition of when the paginated-list function should be emitted by the generator. There's nothing like if parameters[].name == "page". the furthest I got was to iterate through query params of a get-request operation, but even then I wasn't able to condition properly. It seems it's by design:
  https://stackoverflow.com/questions/20345288/check-with-mustache-js-if-parameter-is-a-specific-value

• Then, I was thinking I would add a boolean attribute isPaginated to ['paths'][/project/{id}/devices][get] in the spec. That would allow to distinguish in the mustache templates, but it makes the spec not valid.

This was my template that would generate files like api_device_paginated_lister.go.

templates/api_paginated_lister.mustache:

{{>partial_header}}
package {{packageName}}

{{#operations}}
import (
	"bytes"
	"context"
	"io"
	"net/http"
	"net/url"
{{#imports}}	"{{import}}"
{{/imports}}
)

{{#operation}}

{{isPaginated}}

// The code is just a placeholder, I wanted to know if it's emitted only on paginated methods

func (a *{{{classname}}}Service) {{nickname}}Execute(r {{#structPrefix}}{{&classname}}{{/structPrefix}}{{^structPrefix}}Api{{/structPrefix}}{{operationId}}Request) ({{#returnType}}{{^isArray}}{{^returnTypeIsPrimitive}}{{^isResponseFile}}*{{/isResponseFile}}{{/returnTypeIsPrimitive}}{{/isArray}}{{{.}}}, {{/returnType}}*http.Response, error) {

	var items []{{returnType}}

	pageNumber := int32(1)

	// classname {{classname}}, {{&classname}}


	for {
		page, _, err := r.Page(pageNumber).Execute()
		if err != nil {
			return nil, err
		}

		items = append(items, page.Devices...)
		if page.Meta.GetLastPage() <= page.Meta.GetCurrentPage() {
			break
		}
	}

	return items, nil
}
{{/isPaginated}}

{{/operation}}
{{/operations}}

To consider the templates, we must have config.yaml as

templateDir: /local/templates
files:
  api_paginated_lister.mustache:
    templateType: API
    destinationFilename: _paginated_lister.go

.. and -c config.yaml to the openapi-cli call.

[t0mk]

I also tried to come up with an yq expression that would add a boolean flag isPaginated to ["paths"]["/projects{id}/devices"]["get"]. I came up with

yq 'with(.paths[].get | select(.parameters[].name == "page"); .isPaginated=true)' < $1 > $2

.. but it's not completely correct.

[displague]

@t0mk The Path syntax is well defined, you can't add arbitrary fields unless they follow the x- format.

[displague]

@t0mk page.Devices would also need to be template-ified in your example. I don't presume determining the proper plural is trivial.

[t0mk]

@displague Thanks for the tip on the x- properties, it couldn't a fix for my problem.
https://swagger.io/specification/#paths-object

As for the the plural, I think it can be worked out from the template variables. It might not be gramtatically correct, but I don't think it will conflict.

[ctreatma]

Closing in favor of #150, which will generate the changes in this PR for all paginated endpoints using a combination of vendor extensions and custom templates.