Improve ability to customise theme about docusaurus-openapi

[brittonhayes]

@chris48s @bourdakos1 have there been any developments on the additional language examples functionality you mentioned in number 2? At the very least an update to the docs to indicate to users that they can set something like the following in their theme config:

// working theme config edit to add more languages
  themeConfig:
    /** @type {import('docusaurus-preset-openapi').ThemeConfig} */
    ({
      languageTabs: [
        {
          tabName: "cURL",
          highlight: "bash",
          language: "curl",
          variant: "curl",
          options: {
            longFormat: false,
            followRedirect: true,
            trimRequestBody: true,
          },
        },
        {
          tabName: "Javascript",
          highlight: "javascript",
          language: "javascript",
          variant: "fetch",
          options: {
            ES6_enabled: true,
            trimRequestBody: true,
          },
        },
        ...

I've noticed that while this does generate the code for all supported languages from the postman-code-generator, it doesn't support highlighting for all the languages via prism-react-renderer. For example python, javascript (axios and fetch), and go all highlight perfectly. However when I try the same pattern set for the other languages but specifying something like Dart, Swift, Ruby, or Rust - the highlighting no longer works.

So, TLDR: I think this open issue sounds like a lot of great ideas and I think even just adding more clear support for other language examples as part of these customization enhancements would be quite useful as an end user!

// This generates the code but highlighting does not work
{
    tabName: "Rust",
    highlight: "rust",
    language: "rust",
    variant: "reqwest",
    options: {
      followRedirect: true,
      trimRequestBody: true,
    },
},

[chris48s]

The way we solved this was:

docusaurus-theme-openapi >=0.6.4 allows the Curl component to be swizzled in isolation

We made a custom Curl component which substitutes the placeholder string $url in examples from x-code-samples with postmanRequest.url.toString(): https://github.com/badges/shields/blob/master/frontend/src/theme/ApiDemoPanel/Curl/index.js#L188-L191

We define our code examples in x-code-samples. So our x-code-samples block might look like

"x-code-samples": [
  {
    "lang": "URL",
    "label": "URL",
    "source": "$url"
  },
  {
    "lang": "Markdown",
    "label": "Markdown",
    "source": "![PyPI - License]($url)"
  },
  {
    "lang": "reStructuredText",
    "label": "rSt",
    "source": ".. image:: $url\n:   alt: PyPI - License"
  },
  {
    "lang": "AsciiDoc",
    "label": "AsciiDoc",
    "source": "image:$url[PyPI - License]"
  },
  {
    "lang": "HTML",
    "label": "HTML",
    "source": "<img alt=\"PyPI - License\" src=\"$url\">"
  }
]

..and then the page that generates is https://shields.io/badges/py-pi-license

Not sure how much that helps. This works for us, but it might not be the right solution for everyone. The way we are using this is a bit esoteric in some ways, but quite simple in others.

[bourdakos1]

2 and 3 sound good to me :)

for 1 have you tried swizzling? https://docusaurus.io/docs/swizzling I’ve never done it before, but this sounds like it might be a good use case? If it works we can better document it so that others can easily create their own response panels

[chris48s]

Thanks for the response. I must admit, I am a first-time swizzler 😄 . Conceptually this seems a lot like the solution I was looking for. It also seems like marking certain components as 'safe' means there is already a mechanism to provide a stable plugin interface.

Having had a bit of an experiment, here's some findings:

I was not able to swizzle the Response component in isolation. When run npm run swizzle, it is listed as a component I can swizzle and does spit out a file I can modify, but I still have to swizzle the whole ApiDemoPanel component to get it to pick up the local version of the component, so that didn't really help. Same thing for the Curl component.

My theory is that this is either to do with

• The nested structure (Response is a subdir under ApiDemoPanel) or
• The import statements are relative paths (i.e: import Response from "./Response"; not import Response from "@theme/ApiDemoPanel/Response";, or whatever)

or possibly a combination of both, but I haven't really dug into it.

One thing I was able to do using this approach was I removed the pagination by swizzling the core DocPaginator component and replacing it with

import React from 'react';

export default function DocPaginator(props) {
  return '';
}

so that worked at least.

[bourdakos1]

Yea, I’m guessing it’s the relative imports. Looking at the standard Docusaurus theme, they have a nested structure, but use “@theme/…” for all imports. We should update all of our imports to match.

[brittonhayes]

Thanks so much for the reply! I'll take a look at this and see how you all managed to get the functionality implemented.

[cocowalla]

@brittonhayes did you ever figure out how to get syntax highlighting working with Rust, Java, C# etc?