diff options
author | Robert Fekete <fekete77.robert@gmail.com> | 2022-07-01 01:36:32 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-07-01 01:36:32 +0300 |
commit | 2c86307f68964aab1ee715009575a2c8934d829f (patch) | |
tree | aa6635439c67cb82a2bcd557912636a21c8d322b | |
parent | 8c018e31f0eeac93d73630a480cceaa957cc2d87 (diff) |
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>
-rw-r--r-- | layouts/shortcodes/redoc.html | 91 | ||||
-rw-r--r-- | userguide/content/en/docs/Adding content/Shortcodes/index.md | 15 |
2 files changed, 106 insertions, 0 deletions
diff --git a/layouts/shortcodes/redoc.html b/layouts/shortcodes/redoc.html new file mode 100644 index 0000000..0d4cf09 --- /dev/null +++ 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 index 08192b3..627a3a0 100644 --- 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 |