Remove autogenerated code samples when using x-codesamples

[tjperry07]

Is your feature request related to a problem?

When add x-codeSamples, you have to enable the language in languageTabs to make it appear in the reference. This also makes the auto-generated ones appear.

Describe the solution you'd like

When using x-codeSamples for a specific language, the auto-generated ones should not appear or be a config option I can toggle on and off.

Describe alternatives you've considered

Turning off the language in question entirely
Editing the plugin code directly.
Tried to edit the CSS to hide the block, but they have the same CSS classes.

Additional context

If I went through the effort of creating custom code samples, I don't need the autogenerated ones.

[sserrata]

Hi @tjperry07, thanks for bringing this up...I think there's a couple of approaches to solving for this:

1. Control generated snippets using variants. For example, we could support hiding some or all generated snippets/variants using the variants array, e.g. variants: [], in languageTabs. The change would apply globally across all plugin API configs.
2. Control generated snippets using a plugin config option. For example, we could specify which languages/variants we want to appear. The change would be scoped to the specific API(s).

Some other item/feature to consider would be whether or not custom languages should be supported, or languages that aren't already included in the default language set.

Something else to consider is how x-codeSamples should be supported across endpoints. For example, it's possible that not all endpoints in an API will have the same languages and code samples represented, so the solution would need to be capable of adapting to that, such that code samples and language tabs only appear for those operations containing them.

[tjperry07]

I would do #2. Since languageTabs is mostly from the Postman generator, I think messing with those might get a little messy.

It might be as simple as a check. For x-codeSamples, you have to supply a lang which usually matches the Postman languageTab. If x-codeSamples lang = Python, don't display the python postman tab?

IDK. It's tricky and everyone will have a preference. I would add an option to the plugin to just turn off the Postman languageTabs and replace them with my code samples.

[tjperry07]

I've figured out a workaround for this. Add this to your custom.css. If the app changes, this will stop working.

.tabs-container.openapi-tabs__code-container.openapi-tabs__code-container-inner:nth-child(2) {
  display: none;
}

Basically when there is a custom code sample for the language, it puts in the top row and moves the auto-gen to the bottom. If there is no custom code sample, it moves the auto-gen to the top row. hiding the bottom row means when a user clicks through they only see the custom samples or the auto-gen and not both.

[sserrata]

Btw, with a bit of experimentation I was able to suppress the generated variants simply by passing an empty variants: [] array in languageTabs (option 1). However, it required a couple of changes to CodeSnippets so it isn't technically supported yet. I'll try to work it into the next release, as I feel it should be supported. That said, we could still opt to pursue option 2 as I don't see options 1 and 2 as mutually exclusive.

[mnemitz]

Is there any way to control which snippets get included, or to change the order they appear in?

[tjperry07]

Is there any way to control which snippets get included, or to change the order they appear in?

Just add them in the order you want in the API file.

...
    "/scheduler/rerun": {
      "post": {
        "summary": " Retry Failed Run",
        "tags": [
          "Runs"
        ],
        "description": "Retry a run the point of failure. This endpoint will start the run again and run only the nodes that failed.\n",
        "operationId": "retry-failed-run",
        "x-codeSamples": [
          {
            "lang": "Python",
            "label": "KeyPair Auth",
            "source": {
              "$ref": "./code-samples/rerun/python_requests_keypair.py"
            }
          },
          {
            "lang": "Python",
            "label": "Basic Auth",
            "source": {
              "$ref": "./code-samples/rerun/python_requests_basic.py"
            }
          },
          {
            "lang": "Python",
            "label": "OAuth",
            "source": {
              "$ref": "./code-samples/rerun/python_requests_oauth.py"
            }
          },
...