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^1:

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^2 of the GitHub REST API description webhook schemas are included.

[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!

[ricardoboss]

Have the priorities changed by now? 😄 Any timeline for 3.1 support?

[harritaylor]

adding a +1 for demand here - all our APIs are using OAI3.1 so having to down-convert to 3.0 is a little cumbersome. (also happy to help with contributing!)

[baywet]

No updated timeline to share at this point. You can track the progress in the dependency with this milestone Whenever a preview of the new version is available, we'll be able to start work in kiota.

[jhancock-taxa]

Please make sure that when this is implemented it fully supports proper enums with number/string representation in all languages that generate real enums with real numerical values attached like this:

public enum Example {
  E1 = 1,
  E2 = 2,
  E3 = 4,
  ...etc.
}

The value should always be defined, never left to some automatic guess work based on the starting value too.

See #5165 for examples of what should be correctly outputted as your test case. In the case where the key is a string, languages should use a const static class to represent those if they don't support string/string (i.e. c#)

I've defined an example in #5165 as well of what the OpenAPI 3.1 version looks like.