Compatibility with offline plugin?

[GarlicHiker]

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?

[blueswen]

Could you provide a reproducible project or your mkdocs.yaml and the markdown file using mkdocs-swagger-ui-tag?

[GarlicHiker]

Unfortunately, the project I'm working on right now is proprietary. I can't share the OpenApi specs files. Below is the mkdocs.yaml file.

site_name: Docs
site_url: ""
use_directory_urls: False
theme:
  name: material
  features:
    - navigation.tabs
  palette:
    - scheme: default
      toggle:
        icon: material/brightness-4
        name: Switch to dark mode
      primary: black
      accent: blue
    - scheme: slate
      toggle:
        icon: material/brightness-7
        name: Switch to light mode
      primary: black
      accent: lime

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
  # Python Markdown Extensions
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

plugins:
  - offline
  - swagger-ui-tag:
      background: ""
      docExpansion: full
      filter: ""
      syntaxHighlightTheme: nord  # supported themes:  agate', 'arta', 'monokai', 'nord', 'obsidian', 'tomorrow-night
      tryItOutEnabled: false
      validatorUrl: none

and the .md file where I want to show the docs:

---
hide:
  - navigation
  - toc
---

# Open API

<swagger-ui src="assets/openapi/openapi.json"></swagger-ui>

In the meantime, I realized that the page is acutally not blank, but there is a text: Failed to load API definition. that is normally not visible, but can copied (white font ?). Also, in the developer console in the web browser, there are a few errors (<local path> stands for my localhost path):

swagger-ec7c41ec.html:70 Uncaught DOMException: Failed to read a named property 'update_swagger_ui_iframe_height' from 'Window': Blocked a frame with origin "null" from accessing a cross-origin frame.
    at ResizeObserver.<anonymous> (file://<local path>/swagger-ec7c41ec.html:70:14)
(anonymous) @ swagger-ec7c41ec.html:70

swagger-ec7c41ec.html:55 Uncaught DOMException: Failed to read a named property 'scheme' from 'Window': Blocked a frame with origin "null" from accessing a cross-origin frame.
    at window.onload (file://<local path>/swagger-ec7c41ec.html:55:29)
window.onload @ swagger-ec7c41ec.html:55

(anonymous) @ swagger-ec7c41ec.html:17
swagger-ec7c41ec.html:70 Uncaught DOMException: Failed to read a named property 'update_swagger_ui_iframe_height' from 'Window': Blocked a frame with origin "null" from accessing a cross-origin frame.
    at ResizeObserver.<anonymous> (file://<local_path>/swagger-ec7c41ec.html:70:14)

(anonymous) @ swagger-ec7c41ec.html:70
swagger-ec7c41ec.html:1 Access to fetch at 'file:///<local path>/assets/openapi.json' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, isolated-app, brave, https, chrome-untrusted, data, chrome-extension, chrome.
index.js:20  

GET file:///<local path>/assets/openapi/openapi.json net::ERR_FAILED

swagger-ec7c41ec.html:70 Uncaught DOMException: Failed to read a named property 'update_swagger_ui_iframe_height' from 'Window': Blocked a frame with origin "null" from accessing a cross-origin frame.
    at ResizeObserver.<anonymous> (file://<local path>/swagger-ec7c41ec.html:70:14)
(anonymous) @ swagger-ec7c41ec.html:70

I'm really a newbie in the world of frontend and js, so I really appreciate any help 🙂

[blueswen]

Sorry for the late reply. The MkDocs Swagger UI Tag is not compatible with the Material MkDocs built-in offline plugin due to a cross-origin security issue enforced by the browser by default.

If you really want to use this with the offline plugin, you can add the --allow-file-access-from-files configuration when opening Chrome. However, this may make your Chrome vulnerable. For more details, check https://chrome-allow-file-access-from-file.com/.