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.

[tjperry07]

I want to use the x-code-samples since ours is automated. And like @philsturgeon mentioned many others are automated as well since it was the only solution that existed for a while. It keeps the code samples close to the code base and lets them run as part of a CI/CD pipeline.

I would be interested to understand how portable using templates would be? It seems like the same amount of effort as using a vendor extension.

[marbemac]

@tjperry07 interesting - what are you using to help generate the code samples and add them to your openapi document? is it something open source or custom in house, and if in house I'd love to hear about high level approach ya'll took to programmatically generate the samples :).

[tjperry07]

It's custom. It's not fancy. I pull the code samples from our SDK docs which are maintained by the team. When something new is added they have to create the sample. (I wish I knew how). Then, as part of the CI/CD it grabs changes pulls them into the public docs repo and drops them into the correct code_samples folder.

Our API docs are fully modular so the information can be used in other places. The basic structure looks like this:

├── Parameters
├── README.md
├── api-description
├── code_samples
│   ├── account
│   │   ├── account.java
│   │   ├── account.js
│   │   ├── account.py
│   │   ├── account.rb
│   │   └── account.txt
├── dist
├── examples
├── models
├── reference
└── tag-descriptions

Then I use x-code-samples in my API file to pull in the data

      x-code-samples:
        - lang: bash
          label: cURL
          source: 
            $ref: code_samples/hosted-authentication/curl-get-oauth-authorize.txt

[philsturgeon]

Another vote for the x-code-samples approach came in today. Currently the usage is:

1. OpenAPI is designed and edited through Studio or by hand or whatever.
2. openapi-generator creates SDKs in CI
3. The CI process writes a bunch of code samples to their own files for each operation
4. The CI process post-processes the OpenAPI and stores a copied version that contains the x-code-samples
5. Docs point to that post-processed OpenAPI

This sounds a lot like the use case shared by @tjperry07. ☝🏻

@marbemac when we say "its a lot to maintain" I don't know how many people are doing it by hand.

Your alternative of coming up with a template, there is a concern from the folks I talked to today that they dont even want API designers (modelling melvin) to have to configure that template. They don't want modelling melvins to have to copy and paste that template config to their project or enable it for the docs either. They want a zero-effort approach, and the process they are currently using, and outlined above, would actually handle that because the bog standard OpenAPI is picked up, processed, and published elsewhere, with code samples included at no effort by the modelling melvins.

I think we might have a winner here tbh. "Render the x-code-samples and let people define them however they want" seems to be the least opinionated and the most portable approach.

[tjperry07]

This is a much better explanation of the process we do. 😄 Our API is pretty large
https://developer.nylas.com/docs/api/#overview and you can see each endpoint has code samples.

We do edit in Stoplight https://nylas.stoplight.io/studio/docs (private). If this gets off the ground, feel free to reach out me for testing or any other assistance I can provide.

[SerKnight]

At Xero we started down this route and had SDK specific code samples for each of our 6 languages. It handled things like enums, and expected object structure and casing conventions. However was quickly un-maintainable.

We use HtmlDocs2 to generate our docs, and refactored the 6 example route to instead store more param/field level metadata for our 6 sdks. Then in the mustache templates we use all the vendor extension meta to build up SDK specific examples.

However - this is still not super maintainable and embeds a lot of extra meta data that is very tied to the logic of each languages HtmlDocs2 mustache templates.

End result:
https://xeroapi.github.io/xero-ruby/accounting/index.html

OAS w/ meta to create dynamic code samples

https://raw.githubusercontent.com/XeroAPI/Xero-OpenAPI/master/xero_accounting.yaml

    put:
      security:
        - OAuth2: [accounting.settings]
      tags:
        - Accounting
      operationId: createAccount
      summary: Creates a new chart of accounts
      x-hasAccountingValidationError: true
      x-example:
        - object:
          is_object: true
          key: account
          keyPascal: Account
        - code:
          key: code
          keyPascal: Code
          default: 123456
          object: account
        - name:
          key: name
          keyPascal: Name
          default: FooBar
          object: account
        - type:
          key: type
          keyPascal: Type
          default: EXPENSE
          nonString: true
          php: XeroAPI\XeroPHP\Models\Accounting\AccountType::EXPENSE
          node: AccountType.EXPENSE
          ruby: XeroRuby::Accounting::AccountType::EXPENSE
          python: AccountType.EXPENSE
          java: com.xero.models.accounting.AccountType.EXPENSE
          csharp: AccountType.EXPENSE
          object: account
        - description:
          is_last: true
          key: description
          keyPascal: Description
          default: "Hello World"
          object: account

[avin-kavish]

These action names are very verbose lol.

[wenqi73]

@philsturgeon Hi, is there any progress on this feature?

[avin-kavish]

I think x-code-samples would work. The backend can programmed to generate the code sample as it's api changes.

[avin-kavish]

allow end users to more programmatically produce code samples

Having x-code-sample will enable this, they just need to programmatically insert the programmatically produced code sample into the api doc.

[dbrian57]

I haven't been able to get this to work either. We're currently using the x-codeSamples field with ReDoc, but I've been unable to get Elements to display our custom samples. I've tried: x-code-samples, x-code-sample. Neither work. Does anyone have an example of this working in their spec?

What we currently have:

      x-codeSamples:
        - lang: cURL
          source: |-
            curl -X GET \
              -H "Content-Type: application/json" \
              -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
              "https://api.digitalocean.com/v2/account"

[philsturgeon]

Hi @dbrian57, this is not an implemented feature. We're discussing the potential implementation to see if that would solve the use case for people. It seems like you would like it to work this way, and tbh I don't know of a better solution yet so perhaps we should consider this to be the way to go?

@mnaumanali94 what do you think?

[dbrian57]

Hi @philsturgeon, any updates on this? Just wanted to know if it was on the road map or anything now. Thanks!

[philsturgeon]

I’m just a part time helper these days, @mnaumanali94 is running the show. I just want to make sure a direction is clear so that when it does become time to schedule the work it’s clear what needs to be done.

[dbrian57]

Hi @philsturgeon and @mnaumanali94, that would be amazing. We just like to maintain our own code samples for certain languages. Thanks for getting back to me so quickly!

[sboudouk]

Hello. Elements rocks, however to go production with it, I would like to know if this feature is planned for soon or still on the pipe / backlog ?

Thanks.

[dbrian57]

Would love to know an update on this, too. Thanks!