blueswen/mkdocs-swagger-ui-tag

A MkDocs plugin supports adding Swagger UI to the page.

Hello there 👋

Hi, I am @Blueswen (Yi-Wei, Liu), a Software Engineer focus on Web Application, DevOps, Cloud Native and Developer Experience.

Want to be a full stack developer, but just a stack overflow developer right now.

My Tech Stack

mkdocs-swagger-ui-tag's Issues

OAS 3.1 Dark Mode Contrast

The color contrast in some spots when reading OAS 3.1 is very low and hard to read.

Using the sample OAS 3.1 sample as an example: https://blueswen.github.io/mkdocs-swagger-ui-tag/demo/openapi-v3.1/

All of this text is very difficult for me to read, but I focused on the property name and put it into a whocanuse.com comparison:
https://www.whocanuse.com/?bg=1e2129&fg=3b4150&fs=16&fw=

It gives it a 1.58:1 contrast ratio, compared to the light theme of 6.89:1, https://www.whocanuse.com/?bg=d4e1db&fg=414757&fs=16&fw=

Compare to this to OAS 3.0, which has great contrast of the property names: https://blueswen.github.io/mkdocs-swagger-ui-tag/demo/static-file/

13.93:1 - https://www.whocanuse.com/?bg=1c1f27&fg=e9ebfc&fs=16&fw=

Any chance we increase the contrast used in dark mode for OAS 3.1?

Compatibility with offline plugin?

Hi, my goal is to create completely offline documentation website, working without any server that will be deployed via .zip archive.
But it seems that mkdocs-swagger-ui-tag plugin doesn't work well with offline plugin.

When I visit the documentation website using mkdocs serve, it fully works as expected, but when I compile it using mkdocs build and then go to the page that should contain OpenAPI specs (rendered by mkdocs-swagger-ui-tag javascript), nothing is shown there, except for the H1 heading of the related .md file, where the tag is included.

Am I doing anything wrong?

Dark theme toggle is dependent on slate theme

The Materials theme has the ability to let you define your own colour palette and use that. However, this plugin hardcodes slate as the palette name it checks against in order to toggle dark mode which breaks with any custom, dark, palette.

It would be great if there was some way to indicate to the plugin which palette name it should look for and under which condition to activate the dark mode (as a palette could have a light theme too).

iframe resizing breaks with instant navigation

When turning on instant loading from mkdocs material and the first page that is visited does not contain any swagger ui tags, the resize handler breaks, since the function is not defined on the parent page.

plugins:
  - swagger-ui-tag

theme:
  name: material
  features:
    - navigation.instant

This is the error that is raised:

Uncaught TypeError: parent.update_swagger_ui_iframe_height is not a function
    at ResizeObserver.<anonymous> (swagger-df07ce82.html:69:14)

It is not a race condition, since the update_swagger_ui_iframe_height is never defined. Once a full page refresh is done, the function is there again, and subsequent pages will have it.

The current workaround for us is to disable navigation.instant, but could this be solved in a better way?

Thanks for creating this 💚

Cheers
Andi

Dark theme

Hi! Did you try with the slate theme of Material for MkDocs enabled?

I actually integrated the Swagger UI in some projects docs (with a few lines of Javascript), and it looks nice with a light theme, but is unreadable with a dark theme. Maybe you found a way to improve that.

Is it possible to configure Swagger OAuth 2.0 authorization?

Hi there 👋

In FastAPI there's the option swagger_ui_init_oauth to configure OAuth 2.0 authorization for Swagger. For example:

app = FastAPI(
    title='My API',
    description="My description",
    version="0.1.0",
    swagger_ui_init_oauth={
        "usePkceWithAuthorizationCodeGrant": True,
        "clientId": '****',
        "scopes": ['openid', 'email', 'groups'], },
)

Is it possible to set the parameters (or the complete dict) from swagger_ui_init_oauth using this plugin?
I could not find it in the documentation but maybe I overlooked.

Customizing OpenAPI output with CSS

Hello!

I am using your plugin on MkDocs Material. Now I am trying to customize OpenAPI output with extra CSS, and I'm failed( Please clarify is it possible?

What do I have:

1. docs/css/extra.css and docs/css/extra-swagger-ui.css files
2. Correct pointing to these files in my mkdocs.yml file:

extra_css:
  - css/extra.css
  - css/extra-swagger-ui.css

3. The css/extra-swagger-ui.css file content:

body {
    background-color: white
}

@font-face {
    font-family: "TT_Norms_Pro_Regular";
    src: url('/fonts/ttf/TT Norms Pro Regular.ttf') format('truetype');
}

/* @font-face {
    font-family: "TT_Norms_Pro_Light";
    src: url('/fonts/ttf/TT Norms Pro Medium.ttf') format('truetype');
} */

:root {
    --md-text-font: "TT_Norms_Pro_Regular";
    --md-code-font: "TT_Norms_Pro_Regular";
}

.swagger-ui .p {
    color: black;
    font-family: var(--md-text-font);
    font-size: 1em;
    font-weight: normal;
    line-height: 2;
}

And this CSS does not apply in any way( you can see example here: http://shahid.ru/en/cm_loyalty_online_api/api_requests/

Could you please help me?

Confusing position of the OAuth popup dialog

In the plain generated Swagger documentation the authorization dialog is positioned at the top of the page:

However, in the mkdocs embedded Swagger documentation the authorization dialog is centered in the iframe:

This behaviour can be confusing to users as they need to scroll down after clicking the Authorize button to find the popup.

Not sure if this behaviour can be changed/configured, let me know if I need to supply more details.

Incompatible with "--no-directory-urls"

If you export the documentation with use_directory_urls: false or --no-directory-urls mkdocs crashes with

IsADirectoryError: [Errno 21] Is a directory: '/[...]/index.html'

After disabling swagger-ui-tag it works again.

mkdocs seems to generate the documentation twice with this option and the first time with folders instead of files.

How to use?

How to use?

I have an OpenAPI in yaml format. I want to use that file to generate files in MkDocs.
I cannot generate it in MkDocs even if I save the openapi.yaml file in the docs/assets/javascripts folder.

Am I using it incorrectly?

Thank you in advance.

deepLinking option?

Hi I'm using another plugin to reender with mkdocs an openapi file for a generated documentation and I'm testing yours to replace the old one ^^. I will appreciate to be able to have on the generated site the deepLinking feature : https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/

Do you think that is it possible with your plugin to have this option ? (I'm not sure it's possible due to the iframe usage)

Issue with Special Charaters in Paths

Hi,
we have for example a @ in the Pathname of document Directories.
This leads this plugin is putting the file swagger-<...>.html in ...%40... Directory. Which then is not found in the resulting webpages.

For me it looks if you change line 98 in plugin.py from

page_dir = os.path.dirname(os.path.join(config['site_dir'], page.url))

to

page_dir = os.path.dirname(os.path.join(config['site_dir'], urlunquote(page.url)))

will fix the issue, but I do not know if there is any other side effect.

Would be great if you can have a look in this.
Many thanks.
Kind regards

Not able to customize the swagger UI iframe with website dark and light mode

The problem I am facing is , I am not able to customize the swagger UI iframe in the page.

For better readability, I want to change the colour of text inside the swagger UI which is rendered in light and dark mode.

Right now, I am not able to do that, I added some custom css for the swagger UI texts, and although it is readable, but still the colour of text of the swagger UI iframe (which is rendered using this pluggin) does not changes as i change the mode from dark to light.

can you tell me a way, how I can customize the text colour of swagger UI which is rendered as per light and dark mode and for better readability.

To sum up: I want to change the colour of the text inside the swagger UI rendered docs as per light and dark mode. I want this customization for better readability. Currently, I added some css and made the things readable, but I want the texts of the swagger UI changes as per light and dark mode. If possible, pls help me in this or tell a way to make it work.

Thanks

Do the same for ReDoc

First, thank you very much for your awesome mkdocs plugin!

It would be awesome to do the same for ReDoc, which is a bit nicer, but works nearly the same.

Mkdocs site_url not used to load asset

I host my mkdocs on gitlab pages, inside a group, so the url is: https://namespace.gitlab.io/project.
When using swagger-ui-doc, I specify /assets/openapi.json, which works great when doing a serve. However, when opening the gitlab page, I'm getting 404 because he tries to load the json from https://namespace.gitlab.io/assets/openapi.json, so project is missing here.
In my mkdocs.yml, I tried to specify the site_url then: https://namespace.gitlab.io/project, which still doesn't help. Same result.

Any ideas?

Inbuilt search is not working for content generated by this plugin

Hello,
above all, thank you for creating this plugin! It's awesome!

I stumbled across one issue: when I add the plugin in the suggested way to my project, and build the static website, the OpenAPI specification generated by this plugin seems to be invisible to the default search feature provided by Material for MkDocs. Is the there a known way (a workaround) how to put the searching into operation, or is this a bug to be fixed?
Thank you!

tryItOutEnabled: false is ignored

Setting tryItOutEnabled: false in the plugin's setting is being ignored, since the "Try it out" button is still being displayed and can be toggled.

mkdocs.yml settings:

plugins:
  - search
  - swagger-ui-tag:
      tryItOutEnabled: false

Result:

Schema not being displayed properly when navigating to page via sidebar

When loading a markdown page directly (when running via mkdocs serve), the schema shows up as expected, however, when navigating to that same page via the sidebar, only the first part of the schema is displayed. The chrome console shows the following error:

Uncaught TypeError: parent.update_swagger_ui_iframe_height is not a function at ResizeObserver.<anonymous> (swagger-ff203020.html:49:14)

Everything appears to work as expected when loading a built site, rather than using mkdocs serve.

Anchor links to API calls

Hello!
Thanks for the cool plugin.

In the typical Swagger UI doc, when you click on a certain API request description, an anchor link to that request appears in the browser URL. This link can then be used to go directly to the desired API request description.

Example: https://petstore.swagger.io/#/store/getInventory

The current version of the plugin doesn't have this functionality (or I'm doing something wrong).
Can you improve the plugin?

How to download a specification

"Hello! Thank you for your plugin. We are using version 0.6.4 installed on Mkdocs Material version 9.2.5. We are using it as follows: links to OpenAPI yaml specifications are embedded in markdown pages. We encountered the following behavior: when clicking on the specification link, its text opens in a new tab. Expected behavior: a modal window should open to save the specification. How can we achieve this behavior? I am attaching a screencast showing the actual and desired behavior."

Uploading screencast-bpconcjcammlapcogcnnelfmaeghhagj-2024.02.27-12_11_03.webm…

[performance] Looking up every file is slow

Hello, I've noticed that the processing here can significantly slows down building the docs, probably because of BeautifulSoup.

On my website, running the plugin added an overhead of about 27s. Because I know the files where I want the swagger-ui tags to be used, I've added a simple filename filter patch to avoid trying to lookup on every single file. That improved the performance to only 2s!

def on_post_page(self, output, page, config, **kwargs):
    """Replace swagger-ui tag with iframe
    Add javascript code to update iframe height
    Create a html with Swagger UI for iframe
    """
    if page.file.name not in ("rest_api", "rest-api"):
        return output
    ...

Proposal

My proposal is:

• Add an option (e.g, filter_filenames), which provides an optional list of filenames to match before proceding the processing.
• For backward-compat, if this option is not provided the plugin continue with its current behavior.

What do you think? I can open a PR next week

Table of Contents (TOC)

Hello, thank you for the effort that went into creating this project. I was wondering if it would be possible to add support for rendering a table of contents (TOC) of the API endpoints on the right of the page, which is a feature I am used to in MkDocs.