Question: Can we add additional code samples?

[homotechsual]

This seems not to read the x-codesample from the API spec but is instead generating it's own code examples. So can we hook into that to add, for example, PowerShell examples?

[sserrata]

Hi @homotechsual, you're correct: the code examples are being generated using a forked instance of postman-code-generators. For now, we intentionally limit support to Python, Javascript, Golang, and cURL, to help reduce the overall webpack bundle size. Although we could potentially support more languages we want to be careful about how we introduce them. Ideally, I think it should be a user defined configuration but we would want to pay close attention to how it might impact the overall bundle size. A PR would be most welcome if you're up for it, otherwise, out team will revisit this in the near future.

[homotechsual]

Yeah it's already user-configurable to a degree - as the plugin can read from themeConfig.languageTabs but as you say the actual generator is missing from PowerShell.

I wonder if a hybrid approach might make sense - leveraging x-codesamples/x-code-samples (why do I see both used 🤣 in different example specs) and generating some kind of config like:

languageTabs: [
        {
          tabName: "cURL",
          tabType: "generated",
          highlight: "bash",
          language: "curl",
          codeLanguage: "bash",
          variant: "curl",
          options: {
            longFormat: false,
            followRedirect: true,
            trimRequestBody: true,
          },
        },
        {
          tabName: "Python",
          tabType: "generated",
          highlight: "python",
          language: "python",
          codeLanguage: "python",
          variant: "requests",
          options: {
            followRedirect: true,
            trimRequestBody: true,
          },
        },
        {
          tabName: "Go",
          tabType: "generated",
          highlight: "go",
          language: "go",
          codeLanguage: "go",
          variant: "native",
          options: {
            followRedirect: true,
            trimRequestBody: true,
          },
        },
        {
          tabName: "Node",
          tabType: "generated",
          highlight: "javascript",
          language: "nodejs",
          codeLanguage: "javascript",
          variant: "axios",
          options: {
            ES6_enabled: true,
            followRedirect: true,
            trimRequestBody: true,
          },
        },
        {
          tabName: "PowerShell",
          tabType: "codesample",
          highlight: "powershell",
          language: "powershell",
          codeLanguage: "powershell",
          variant: "restmethod",
          options: {
            followRedirect: true,
            trimRequestBody: true,
          },
        },
      ]

In any event I'll dig into what it would look like to add PowerShell since the user-configurable part already works.

[homotechsual]

@sserrata could you point at where the various "allowed" languages are controlled, from what I see here:

docusaurus-openapi-docs/packages/docusaurus-theme-openapi-docs/src/theme/ApiDemoPanel/Curl/index.tsx

Line 144 in ffaf42b

codegen.convert(

I should be able to define languages in themeConfig.languageTabs and I do but the new tab loads the first code example (Linux) and then eventually if I switch tabs it just goes blank and crashes the tab section.

What I can't see is where the allowable languages or loaded language plugins (if that's the right term) are defined - it looks like the fork of the code generators still includes the languages like PowerShell etc.

[sserrata]

I wonder if a hybrid approach might make sense - leveraging x-codesamples/x-code-samples (why do I see both used 🤣 in different example specs) and generating some kind of config like:

😄 Yeah, the x-* is just a convention for extensions so it's not uncommon to find variations. One thing to factor in is that the generated code samples change depending on the inputs/form values, whereas x-code-samples would ostensibly be static.

could you point at where the various "allowed" languages are controlled

They're externally limited in the PaloAltoNetworks/postman-code-generators panw-develop branch under the codegens directory. It's possible they could be added back, without (much) impact to bundle size. Also, I was proposing that the languages should be a Plugin Configuration option, so it can be configured per API.

it looks like the fork of the code generators still includes the languages like PowerShell etc.

It's published from the panw-develop branch. See the link referenced above. In theory, we would just need to add the missing languages back to the codegens directory coupled with adding them to the languageTabs object mentioned above.

[sserrata]

Will revisit in the future with goal of allowing users to select which languages they want to support.