Redoc shortcode (#1052)

* Adds redoc shortcode * Documents redoc shortcode * Change example to URL instead of local file * Fix html and redoc options Co-authored-by: LisaFC <lcarey@google.com>
google · Jun 30, 2022 · 2c86307 · 2c86307
1 parent 8c018e3
commit 2c86307
Show file tree

Hide file tree

Showing 2 changed files with 106 additions and 0 deletions.
diff --git a/layouts/shortcodes/redoc.html b/layouts/shortcodes/redoc.html
@@ -0,0 +1,91 @@
+{{- $file := .Get 0 -}}
+{{- $url := "" -}}
+{{- $otheroptions := .Get 1 -}}
+
+{{ if hasPrefix $file "http"}}
+    {{- $url = $file -}}
+{{ else }}
+    {{ if (fileExists (print .Page.File.Dir $file)) -}}
+        <!-- First try as relative path -->
+        {{- $url = (print .Page.Site.BaseURL .Page.File.Dir $file) -}}
+    {{ else }}
+        <!-- Then as project-relative path-->
+        {{- $url = (print .Page.Site.BaseURL $file) -}}
+    {{- end }}
+{{- end -}}
+
+        <!-- CSS style overrides for Redoc API docs -->
+        <style>
+          #redoc input { height: 64px; }
+          #redoc span[type="put"], span[type="get"], span[type="delete"], span[type="post"], span[type="options"], span[type="patch"], span[type="basic"], span[type="link"], span[type="head"] {
+              border-radius: 4px;
+            }
+          #redoc h2 { margin-top: 0px;}
+      </style>
+
+    <!-- Back to top button start -->
+    <style>
+      #myBtn {
+        display: none;
+        position: fixed;
+        bottom: 20px;
+        right: 30px;
+        z-index: 99;
+        font-size: 18px;
+        border: none;
+        outline: none;
+        background-color: #30638E;
+        color: white;
+        cursor: pointer;
+        padding: 15px;
+        border-radius: 4px;
+      }
+
+      #myBtn:hover {
+        background-color: #555;
+      }
+  </style>
+  <button onclick="topFunction()" id="myBtn" title="Go to top">Top</button>
+  <script>
+      //Get the button
+      var mybutton = document.getElementById("myBtn");
+
+      // When the user scrolls down 20px from the top of the document, show the button
+      window.onscroll = function() {scrollFunction()};
+
+      function scrollFunction() {
+        if (document.body.scrollTop > 20 || document.documentElement.scrollTop > 20) {
+          mybutton.style.display = "block";
+        } else {
+          mybutton.style.display = "none";
+        }
+      }
+
+      // When the user clicks on the button, scroll to the top of the document
+      function topFunction() {
+        document.body.scrollTop = 0;
+        document.documentElement.scrollTop = 0;
+      }
+  </script>
+    <!-- Back to top button end -->
+
+    <!--
+    Redoc doesn't change outer page styles
+    -->
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+      }
+    </style>
+
+    <!--
+    Redoc element with link to your OpenAPI definition
+    -->
+   <div id="redoc-container">
+   <redoc spec-url='{{ $url }}' hide-hostname="true" suppress-warnings="true" lazy-rendering  native-scrollbars scroll-y-offset=".js-navbar-scroll" {{ $otheroptions }}></redoc>
+   </div>
+    <!--
+    Link to Redoc JavaScript on CDN for rendering standalone element
+    -->
+    <script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"></script>
diff --git a/userguide/content/en/docs/Adding content/Shortcodes/index.md b/userguide/content/en/docs/Adding content/Shortcodes/index.md
@@ -288,6 +288,21 @@ description: Reference for the Pet Store API
 
 You can customize Swagger UI's look and feel by overriding Swagger's CSS or by editing and compiling a [Swagger UI dist](https://github.com/swagger-api/swagger-ui) yourself and replace `themes/docsy/static/css/swagger-ui.css`.
 
+### redoc
+
+The `redoc` shortcode uses the open-source [Redoc](https://github.com/Redocly/redoc) tool to render reference API documentation from an OpenAPI YAML or JSON file. This can be hosted anywhere you like, for example in your site's root [`/static` folder](/docs/adding-content/content/#adding-static-content), but you can use a URL as well, for example:
+
+```yaml
+---
+title: "Pet Store API"
+type: docs
+weight: 1
+description: Reference for the Pet Store API
+---
+
+{{</* redoc "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/yaml/petstore.yaml" */>}}
+```
+
 ### iframe
 
 With this shortcode you can embed external content into a Docsy page as an inline frame (`iframe`) - see: https://www.w3schools.com/tags/tag_iframe.asp