Include a custom extension in the sliced OpenAPI description

[maisarissi]

As part of the Kiota generation for both clients and plugins, Kiota slices the OpenAPI description based on pre-selection of endpoints provided by the user (both in Kiota CLI and Kiota VS Code)

We should add a custom extension to identify those OpenAPI descriptions created by Kiota:

x-generator: kiota/1.8 kiota-vs/1.8.1

DevProxy does something like this when generating an OpenAPI:

  "x-ms-generated-by": {
    "toolName": "Dev Proxy",
    "toolVersion": "0.17.1"
  }

This can helps us understanding which Kiota version was used to slice the OpenAPI and identify errors.

Acceptance Criteria

• [ ] Add a custom extension "x-generator" when slicing the OpenAPI description on the top of the document if there is none
• [ ] Modify an existing extension by adding our information to the front of the list if it was not there
• [ ] Modify an existing extension by updating our information if it already was there
• [ ] Update the custom extension with the Kiota and VS Code extension version every time a specific client/plugin is re-generated
• [ ] The custom extension should only be updated when there was a regeneration for that specific client/plugin

[baywet]

Is this extension format/information/name already in use somewhere? Have we looked at potential existing extensions we could reuse instead? Could you create a specification for that extension here please? https://github.com/microsoft/OpenAPI/tree/main/extensions

[petrhollayms]

@darrelmiller How do you see it for GA?

[maisarissi]

Is this extension format/information/name already in use somewhere?

This is being used by Dev Proxy, so I thought we could follow the same pattern. @darrelmiller mentioned that TypeSpec might be using something different.

[sebastienlevert]

I don't feel this is needed for GA. @maisarissi?

[maisarissi]

I would say this could help us to get some data around DCs and plugins generated by Kiota, as we would add this when slicing. It would be a nice to have, not blocking request though.

[darrelmiller]

So, there is some precedent here from NSwag with the x-generator extension. https://github.com/search?q=x-generator+path%3A**%2Fopenapi.yaml&type=code

Unfortunately, they invented some strange nested format instead of just borrowing from UserAgent. I do like the idea of being able to record multiple entries though.

How do folks feel about reusing x-generator but with user agent syntax like we use for SdkVersion?

x-generator:  kiota/1.2(comment goes here) blahTool/2.3 blingtool/1.2(another comment)

Same rules as user agent, i.e. last tool adds their name to the front of the list.

[sebastienlevert]

x-generator: kiota/1.8 kiota-vs/1.8.1

That way we can easily define where and how an OpenAPI was generated?

[maisarissi]

Yes! Let's go with x-generator. I think we should have a kiota-cli and a kiota-vs so we can know whether the user just used the CLI or the VS Code (that uses the CLI) 😄 Helps us identifying bugs that are applicable just in the extension.