openapi: replace implementation with swagger-ui #523

README.md

@@ -56,7 +56,7 @@ The Relearn theme is a fork of the great [Learn theme](https://github.com/matcor
   - [Mermaid diagrams for flowcharts, sequences, gantts, pie, etc.](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/mermaid)
   - [Colorful boxes](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/notice)
   - [Reveal you site's configuration parameter](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/siteparam)
-  - [Swagger UI for your OpenAPI Specifications](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/swagger)
+  - [Swagger UI for your OpenAPI Specifications](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/openapi)
   - [Tabbed panels](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/tabs)
 
 ## Installation & Usage

exampleSite/content/_index.en.md

@@ -59,7 +59,7 @@ The theme is a fork of the great [Learn theme](https://github.com/matcornic/hugo
   - [Mermaid diagrams for flowcharts, sequences, gantts, pie, etc.]({{%relref "shortcodes/mermaid" %}})
   - [Colorful boxes]({{%relref "shortcodes/notice" %}})
   - [Reveal you site's configuration parameter]({{%relref "shortcodes/siteparam" %}})
-  - [Swagger UI for your OpenAPI Specifications]({{%relref "shortcodes/swagger" %}})
+  - [Swagger UI for your OpenAPI specifications]({{%relref "shortcodes/openapi" %}})
   - [Tabbed panels]({{%relref "shortcodes/tabs" %}})
 
 ## Support

exampleSite/content/basics/configuration/_index.en.md

@@ -64,12 +64,10 @@ Note that some of these parameters are explained in details in other sections of
   customMermaidURL = "https://unpkg.com/mermaid/dist/mermaid.min.js"
   # Initialization parameter for Mermaid, see Mermaid documentation
   mermaidInitialize = "{ \"theme\": \"default\" }"
-  # If set to false, load the Swagger module on every page regardless if a Swagger shortcode is present
-  disableSwagger = false
-  # Specifies the remote location of the RapiDoc js
-  customSwaggerURL = "https://unpkg.com/rapidoc/dist/rapidoc-min.js"
-  # Initialization parameter for Swagger, see RapiDoc documentation
-  swaggerInitialize = "{ \"theme\": \"light\" }"
+  # If set to false, load the OpenAPI module on every page regardless if a OpenAPI shortcode is present
+  disableOpenapi = false
+  # Specifies the remote location of the swagger-ui js
+  customOpenapiURL = "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
   # Hide Next and Previous page buttons normally displayed full height beside content
   disableNextPrev = true
   # Order sections in menu by "weight" or "title". Default to "weight";

exampleSite/content/basics/migration/_index.en.md

@@ -18,6 +18,14 @@ This document shows you what's new in the latest release. For a detailed list of
 
 ---
 
+## 5.13.0 (2023-05-14)
+
+- {{% badge style="note" title=" " %}}Change{{% /badge %}} The `swagger` shortcode was deprecated in favor for the  [`openapi` shortcode]({{% relref "shortcodes/openapi" %}}). You don't need to change anything yet as the old name will be used as a fallback. It is planned to remove the `swagger` shortcode in the next major release.
+
+  Additionally, the implemantion of this shortcode was switched from RapiDoc to [SwaggerUI](https://github.com/swagger-api/swagger-ui).
+
+---
+
 ## 5.12.0 (2023-05-04)
 
 - {{% badge style="note" title=" " %}}Change{{% /badge %}} In the effort to comply with WCAG standards, the implementation of the collapsible menu was changed (again). While Internet Explorer 11 has issues in displaying it, the functionality still works.
@@ -182,7 +190,7 @@ This document shows you what's new in the latest release. For a detailed list of
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} [Image formatting]({{% relref "cont/markdown#add-css-classes" %}}) has two new classes to align images to the `left` or `right`. Additionally, the already existing `inline` option is now documented.
 
-- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Printing for the [`swagger` shortcode]({{% relref "shortcodes/swagger" %}}) was optimized to expand sections that are usually closed in interactive mode. This requires [print support]({{%relref "basics/configuration#activate-print-support" %}}) to be configured.
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Printing for the [`swagger` shortcode]({{% relref "shortcodes/openapi" %}}) was optimized to expand sections that are usually closed in interactive mode. This requires [print support]({{%relref "basics/configuration#activate-print-support" %}}) to be configured.
 
 ---
 
@@ -295,7 +303,7 @@ This document shows you what's new in the latest release. For a detailed list of
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Introduction of new CSS variables to set the font. The theme distinguishes between `--MAIN-font` for all content text and `--CODE-font` for inline or block code. There are additional overrides for all headings. See the [theme variant generator]({{%relref "basics/generator" %}}) of the exampleSite for all available variables.
 
-- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The new shortcode `swagger` is available to include a UI for REST OpenAPI Specifications. See the [documentation]({{% relref "shortcodes/swagger" %}}) for available features. This feature will not work with Internet Explorer 11.
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The new shortcode `swagger` is available to include a UI for REST OpenAPI specifications. See the [documentation]({{% relref "shortcodes/openapi" %}}) for available features. This feature will not work with Internet Explorer 11.
 
 ---
 

exampleSite/content/dev/contributing/_index.en.md

@@ -49,7 +49,7 @@ Following is an impomplete list of some of the used conventional commit types. B
 |            | rss        | clipboard       | math        |
 |            | variant    | syntaxhighlight | mermaid     |
 |            |            | boxes           | notice      |
+|            |            |                 | openapi     |
 |            |            |                 | piratify    |
 |            |            |                 | siteparam   |
-|            |            |                 | swagger     |
 |            |            |                 | tabs        |

exampleSite/content/more/credits/_index.en.md

@@ -30,7 +30,7 @@ Many thanks to [Andy Miller](https://github.com/rhukster) for initially creating
 - [MathJax](https://mathjax.org/) - Beautiful math and chemical formulae in all browsers
 - [Mermaid](https://mermaid-js.github.io/mermaid) - Generation of diagram and flowchart from text in a similar manner as markdown
 - [Perfect Scrollbar](https://perfectscrollbar.com) - A minimalistic but perfect custom scrollbar plugin
-- [RapiDoc](https://mrin9.github.io/RapiDoc) - Create beautiful, customizable, interactive API documentation from OpenAPI Specifications
+- [SwaggerUI](https://github.com/swagger-api/swagger-ui) - Generate beautiful documentation from a Swagger-compliant API
 - [WorkSans](https://weiweihuanghuang.github.io/Work-Sans/) - Work Sans is a 9 weight typeface family based loosely on early Grotesques
 
 ## Tooling

exampleSite/content/shortcodes/openapi/_index.en.md

@@ -0,0 +1,56 @@
+---
+description: "UI for your OpenAPI / Swagger specifications"
+title: "OpenAPI"
+---
+
+The `openapi` shortcode uses the [Swagger UI](https://github.com/swagger-api/swagger-ui) library to display your OpenAPI / Swagger specifications.
+
+{{% notice note %}}
+This only works in modern browsers.
+{{% /notice %}}
+
+## Usage
+
+While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.
+
+{{< tabs groupId="shortcode-parameter">}}
+{{% tab name="shortcode" %}}
+
+````go
+{{</* openapi src="https://petstore3.openapi.io/api/v3/openapi.json" */>}}
+````
+
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/openapi.html" (dict
+  "context" .
+  "src" "https://petstore3.openapi.io/api/v3/openapi.json"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Parameter
+
+| Name                 | Default          | Notes       |
+|:---------------------|:-----------------|:------------|
+| **src**              | _&lt;empty&gt;_  | The URL to the OpenAPI specification file. This can be relative to the URL of your page if it is a leaf or branch bundle. |
+
+{{% notice note %}}
+If you want to print out (or generate a PDF) from your OpenAPI documentation, don't initiate printing directly from the page because the elements are optimized for interactive usage in a browser.
+
+Instead, open the [print preview]({{% relref "basics/configuration/#activate-print-support" %}}) in your browser and initiate printing from that page. This page is optimized for reading and expands most of the available sections.
+{{% /notice %}}
+
+## Example
+
+### Using Local File
+
+````go
+{{</* openapi src="petstore.json" */>}}
+````
+
+{{< openapi src="petstore.json" >}}

exampleSite/content/shortcodes/openapi/_index.pir.md

@@ -0,0 +1,5 @@
+---
+description: "Adds UI fer yer OpenAPI / Swaggerrr Specificat'ns"
+title: "OpenAPI"
+---
+{{< piratify true >}}