Add support for handling OpenAPI v3.1 definitions

[julealgon]

We started using Kiota recently for a new integration, but the OpenAPI definition for the API we were to interface with uses the v3.1 OpenAPI spec. When attempting to generate a client for this spec, we get the following error message:

crit: Kiota.Builder.KiotaBuilder[0]
      error generating the client: OpenAPI specification version '3.1.0' is not supported.

This forced us to down-convert the definition from v3.1 to v3.0 to be able to use Kiota to generate a C# client for it.

We'd like for Kiota to be able to handle OpenAPI v3.1 natively, so that we don't have to perform this extra, lossy conversion step. The conversion increases maintenance substantially for us, since now we cannot refer directly to the target API's OpenAPI definition, and instead, forces us to maintain a local converted definition file ourselves. Additionally, whenever the target API definition changes in any way, we are then required to perform the conversion step manually again and update our converted file, to only then be able to run Kiota on it again to generate the updated proxy.

For reference, this is the definition we are currently targeting (from SendGrid):

• https://raw.githubusercontent.com/sendgrid/sendgrid-oai/main/oas_v3.json

[baywet]

Hi @julealgon,
Thanks for using kiota and for reaching out.
Kiota relies on OpenAPI.net to parse the descriptions, a library which is also owned by my team.
It doesn't support 3.1 yet, but we're making progress towards it
Once the support is finalized, we should be able to add it here as well fairly quickly, which should also unblock a number of scenarios (like dictionaries/maps etc...)
Keeping this issue opened for now

[JamieMagee]

@baywet Once OpenAPI 3.1 support is finalized, is support for generation of webhooks planned? I currently maintain https://github.com/octokit/webhooks.net manually, but am eager to switch over to automatic generation if possible.

[baywet]

@JamieMagee if by generation of webhooks you mean generating the models for the incoming requests, sure we could add that.
If you mean something else, can you clarify please?

[JamieMagee]

@baywet yes, that's exactly what I am talking about. A top level webhooks property was added as part of the OpenAPI 3.1 spec¹:

Major Changes in OpenAPI Specification 3.1.0
...

• New top-level element for describing Webhooks that are registered and managed out of band

As of release v2.1.0² of the GitHub REST API description webhook schemas are included.

Footnotes

1. https://www.openapis.org/blog/2021/02/18/openapi-specification-3-1-released ↩

2. https://github.com/github/rest-api-description/releases/tag/v2.1.0 ↩

[baywet]

Thanks for clarifying!

[mrBen]

Hello,
In the OpenAPI.NET repo, the issue about 3.1 support is closed.
Should we expect Kiota to support v3.1 soon?

[sebastienlevert]

Yes! It's absolutely something we'll start working on soon as there is a lot of demand for it!

We have some other priorities right now but this should be in the next bucket of improvements!