New fields for client code snippets

[baywet]

One of the main scenarios to use OpenAPI is to generate documentation for humans to read.

The specification does a great job at describing all the aspects to craft the HTTP request, and deal with the HTTP response. It also provides "places" to provide examples for both (example, and examples fields). Those are great when using "barebone" HTTP clients on the platform, and crafting payloads manually.

However, more often than not, the API producer may also provide SDKs, or want to provide end to end code snippets for a given operation with the native client for the platform.

I propose that we create such a place so people don't have to rely on extensions for such things! (could be in a SAF as well, depending on where the SAF discussion goes). Here is a quick example

openapi: 3.3.0
paths:
  "/foo":
    get:
      content:
        "application/json":
           schema:
             type: object
             # the usual stuff
           # this part is new
           snippets:
             "shell/curl": |
               curl "/foo"
             "python/httpx": |
               import httpx
               httpx.get('https://www.example.org/')
             "csharp/kiota;v=1": |
               using MyClient;
               var client = new MyClient(new AnonymousAuthenticationProvider());
               await client.Foo.GetAsync();

Here a couple of things are interesting:

The snippets entry is at the media type level, this is to account for operations that support multiple media types (e.g. json vs event stream) which would require different client code.

The language part (shell, python, csharp) in the entries would rely on a registry we operate, since there doesn't seem to be an registry for programming languages other than implementations that are specific to platforms (e.g. linguist for GitHub)

The client part (curl, httpx, kiota) could either be another registry, or "free" for anybody to use as they which.

The version part is optional, and can be used in case multiple versions of the same client are being supported/showcased.

Thoughts?

[ralfhandl]

Just off the top of my head:

• Isn’t that something that LLMs can generate from an OAD?
• Should the field be named clientCodeSnippets?
• Do we need a registry for client languages?

[baywet]

yes, you can generate them for trivial operations, but the quality varies, and for more complex operations sometimes a handcrafted snippet it more illustrative.
sure, we can debate the better name, I don't have any strong preference either way.

the reason why I'm bringing a registry is to enable better interoperability between the descriptions and tools. Obviously we don't want to end up a couple of years down the road with descriptions containing C#, CSharp, C-Sharp, CS, etc... And I couldn't find one that is "administered" (RFC, IANA, etc...) and not implementation specific (like GitHub Linguist)

[lornajane]

We could formalise x-codeSamples since it seems to be fairly widely adopted. Or is there something about the "in the wild" implementation that you particularly wanted to avoid, @baywet ?