Add an option to desactive browser cache for openapi files

Author: ggrebert

demo-mkdocs/docs/demo/nocache.md

@@ -0,0 +1,13 @@
+Disable browser cache.
+
+## Markdown
+
+```html
+<swagger-ui nocache src="./openapi-spec/sample.yaml"/>
+<swagger-ui nocache src="https://petstore.swagger.io/v2/swagger.json"/>
+```
+
+## Swagger UI
+
+<swagger-ui nocache src="./openapi-spec/sample.yaml"/>
+<swagger-ui nocache src="https://petstore.swagger.io/v2/swagger.json"/>

mkdocs_swagger_ui_tag/plugin.py

@@ -177,6 +177,7 @@ def render_template(openapi_spec_url, swagger_ui_ele):
                 css_dir=css_dir,
                 extra_css_files=extra_css_files,
                 js_dir=js_dir,
+                nocache=swagger_ui_ele.has_attr("nocache"),
                 background=self.config["background"],
                 id="{{ID_PLACEHOLDER}}",  # ID is unknown yet - it's the hash of the content.
                 openapi_spec_url=openapi_spec_url,

mkdocs_swagger_ui_tag/swagger-ui/swagger.html

@@ -17,6 +17,25 @@
   <script src="{{ js_dir }}swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
   <script>
     window.onload = function () {
+      {% if openapi_spec_url is string %}
+        var url = "{{openapi_spec_url}}";
+        {% if nocache %}
+        url += (url.includes('?') ? '&' : '?') + "nocache=" + new Date().getTime();
+        {% endif %}
+      {% elif openapi_spec_url is sequence %}
+        var urls = [
+        {% for item in openapi_spec_url %}
+          {url:"{{item.url}}", name:"{{item.name}}"},
+        {% endfor %}
+        ];
+        {% if nocache %}
+        urls = urls.map(function(item){
+          var url = item.url;
+          url += (url.includes('?') ? '&' : '?') + "nocache=" + new Date().getTime();
+          return {url: url, name: item.name};
+        });
+        {% endif %}
+      {% endif %}
       window.ui = SwaggerUIBundle({
         dom_id: "#swagger-ui",
         onComplete: onComplete,
@@ -25,13 +44,9 @@
           SwaggerUIStandalonePreset
         ],
         {% if openapi_spec_url is string %}
-        url: "{{openapi_spec_url}}",
+        url,
         {% elif openapi_spec_url is sequence %}
-        urls: [
-        {% for item in openapi_spec_url %}
-          {url:"{{item.url}}", name:"{{item.name}}"},
-        {% endfor %}
-        ],
+        urls,
         layout: "StandaloneLayout",
         {% endif %}
         {% if oauth2_redirect_url.startswith('.') %}

tests/fixtures/docs/nocache.md

@@ -0,0 +1,3 @@
+<swagger-ui nocache src="./openapi-spec/sample.yaml"/>
+<swagger-ui nocache src="./openapi-spec/sample.yaml?doudou=doudou"/>
+<swagger-ui nocache src="https://petstore.swagger.io/v2/swagger.json"/>

tests/test_builds.py

@@ -136,7 +136,7 @@ def validate_iframe(html_content, iframe_src_dir):
         iframe_src = iframe_tag.attrs.get("src")
         assert iframe_id is not None
         assert iframe_src is not None
-        assert f"swagger-{iframe_id}.html" == iframe_src
+        assert f"swagger-{iframe_id}.html" in iframe_src
         iframe_file = iframe_src_dir / iframe_src
         assert iframe_file.exists()
         iframe_content = iframe_file.read_text(encoding="utf8")
@@ -199,7 +199,7 @@ def test_basic(tmp_path):
 
     # validate OpenAPI spec exist
     regex_obj = re.search(
-        r'url: "(.*)"',
+        r'var url = "(.*)"',
         iframe_contents,
     )
     assert regex_obj
@@ -224,7 +224,7 @@ def test_basic_sub_dir(tmp_path):
 
     # validate OpenAPI spec exists
     regex_obj = re.search(
-        r'url: "(.*)"',
+        r'var url = "(.*)"',
         iframe_contents,
     )
     assert regex_obj
@@ -251,7 +251,7 @@ def test_use_directory_urls(tmp_path):
 
     # validate OpenAPI spec exist
     regex_obj = re.search(
-        r'url: "(.*)"',
+        r'var url = "(.*)"',
         iframe_contents,
     )
     assert regex_obj
@@ -278,7 +278,7 @@ def test_use_directory_urls_sub_dir(tmp_path):
 
     # validate OpenAPI spec exist
     regex_obj = re.search(
-        r'url: "(.*)"',
+        r'var url = "(.*)"',
         iframe_contents,
     )
     assert regex_obj
@@ -305,7 +305,7 @@ def test_material(tmp_path):
 
     # validate OpenAPI spec exist
     regex_obj = re.search(
-        r'url: "(.*)"',
+        r'var url = "(.*)"',
         iframe_contents,
     )
     assert regex_obj
@@ -340,7 +340,7 @@ def test_url(tmp_path):
 
     # validate OpenAPI spec exist
     regex_obj = re.search(
-        r'url: "(.*)"',
+        r'var url = "(.*)"',
         iframe_contents,
     )
     assert regex_obj
@@ -361,7 +361,7 @@ def test_multiple(tmp_path):
     for ind, iframe_contents in enumerate(iframe_content_list):
         # validate OpenAPI spec exist
         regex_obj = re.search(
-            r'url: "(.*)"',
+            r'var url = "(.*)"',
             iframe_contents,
         )
         assert regex_obj
@@ -396,7 +396,7 @@ def test_build_in_multiple(tmp_path):
                     assert (file.parent / spec_url).resolve().exists()
         elif ind == 1:
             regex_obj = re.search(
-                r'url: "(.*)"',
+                r'var url = "(.*)"',
                 iframe_contents,
             )
             assert regex_obj