Custom SDK/Code Samples

[philsturgeon]

User story.

As an end user of API docs I can see an example of the SDK code for any given operation so long as its defined.

Is your feature request related to a problem?

Currently we help out the majority of users who do not have a custom SDK developed, meaning they immediately have code their end users can use to make requests. For the advanced minority who have their own SDKs, this is a step backwards.

Describe the solution you'd like

The closest thing the OpenAPI community has to a standard way to handle code samples is the x-codeSamples vendor extension started by our friends over at ReDoc.

• if x-codeSamples is missing for an operation, do exactly what we do now and generate samples
• if x-codeSamples exists for an operation, only show curl + the language selector for the languages defined in x-codeSamples
  • the x-codeSamples language selector will not have a library selector
  • If they only define a code sample for Java, that's ok, we only show curl and Java.

[marbemac]

I'm not too keen on the x-codeSamples solution - far too much effort to maintain IMHO.

Never got around to proving it out but I always thought it could be interesting to leverage a simple templating language like mustache etc to allow end users to more programmatically produce code samples for operations in a scalable way.