OpenAPI error: Can't build JumpCloud OpenAPI client

[pquerna]

Kiota is unable to build code for an OpenAPI spec that includes : in the parameters names, along with other errors.

Example OpenAPI Spec: https://docs.jumpcloud.com/api/2.0/index.yaml

(this spec file passes the openapi online validator)

ran via docker:

docker run --rm -v \
        "${PWD}/jcapi:/app/output" \
        mcr.microsoft.com/openapi/kiota generate \
        --openapi https://docs.jumpcloud.com/api/2.0/index.yaml \
        --language Go -n jcapi

trying to build it, here are example errors:

fail: Kiota.Builder.KiotaBuilder[0]
      OpenAPI error: #/definitions/AutotaskMappingRequestContract/properties/id/type - Cannot create a scalar value from this type of node.

fail: Kiota.Builder.KiotaBuilder[0]
      OpenAPI error:  - maxItems is not a valid property at #/paths/~1bulk~1userstates~1eventlist~1next/get/parameters

fail: Kiota.Builder.KiotaBuilder[0]
      OpenAPI error: #/components - The key 'trait:userId:userId' in 'parameters' of components MUST match the regular expression '^[a-zA-Z0-9\.\-_]+$'.

[baywet]

Hi @pquerna,

Thanks for your interest in Kiota and for reaching out.

This OpenAPI description is invalid. Keys MUST match the regex outlined in your log trace as mandated per the specification MaxItems is defined in JSON schema, for which support was added in OAS3.0 but this description is using OAS2.0. The description should be upgraded or the field removed. Using arrays for types is only supported by JSON schema draft 2020-12, which is added with OAS3.1. Either upgrade the version of the description or use nullable: true.

You might want to checkout hidi to convert your description from 2.0 to 3.0.

Note: 3.1 is not supported by hidi or kiota yet, but we're working on adding support for it.

[pquerna]

Hi @pquerna,

Thanks for your interest in Kiota and for reaching out.

This OpenAPI description is invalid. Keys MUST match the regex outlined in your log trace as mandated per the specification MaxItems is defined in JSON schema, for which support was added in OAS3.0 but this description is using OAS2.0. The description should be upgraded or the field removed. Using arrays for types is only supported by JSON schema draft 2020-12, which is added with OAS3.1. Either upgrade the version of the description or use nullable: true.

You might want to checkout hidi to convert your description from 2.0 to 3.0.

Note: 3.1 is not supported by hidi or kiota yet, but we're working on adding support for it.

Thanks for the notes @baywet -- I'm not part of JumpCloud -- I'm wondering from your point of view, is the "right pattern" to patch their upstream OpenAPI spec in my repo to fix these issues? Or have you tried taking these kinds of issues to the upstream company before?

[baywet]

This is something where we're still trying to figure out the model to be transparent on the matter. Ideally API producers would take the feedback/contributions from API consumers and try to refine their description the best they can. It's the most efficient thing for everyone, not only it enables self-served consumption of APIs and frees resources previously dedicated to building clients (when the API producers had enough staff to do so), it also improves the API side story (their linting/security/proxy/etc... tooling benefits from a more precise description).

However we're aware is not necessarily always going to be the case (API producers can sometimes have other priorities or be unresponsive), which is when a local override/updated version of the API description that lives next to the client makes a lot of sense.

Lastly, the ability to filter API paths to only what the client application needs (--include/exclude-patterns) is also a way to circumvent such issues: if an endpoint is causing issues at generation and your application doesn't need it, just exclude it).

I hope that context helps.