Integrate REST API documentation in Docusaurus website (#7)

* Add docusaurus-plugin-openapi-docs
* Document how to update the OpenAPI documentation
* Move documentation links from top to sidebar
* Expand "User Guide" category automatically
* Upgrade Docusaurus from 3.4.0 to 3.5.2
* Upgrade Yarn from 4.1.0 to 4.4.1
* Generate REST API documenation

.yarnrc.yml

@@ -2,4 +2,6 @@ compressionLevel: mixed
 
 enableGlobalCache: false
 
-yarnPath: .yarn/releases/yarn-4.1.0.cjs
+nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-4.4.1.cjs

README.md

@@ -5,40 +5,65 @@
 This repository contains the OpenRemote documentation hosted on https://docs.openremote.io/ as Markdown files in the [docs directory](docs).
 
 The documentation website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+The OpenAPI documentation is generated using the [Docusaurus OpenAPI Docs](https://docusaurus-openapi.tryingpan.dev/) plug-in.
 
 ### Installation
 
-```
+```shell
 $ yarn
 ```
 
 ### Local Development
 
-```
+```shell
 $ yarn start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
 ### Build
 
-```
+```shell
 $ yarn build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
+When the static content has been generated it can be tested using:
+
+```shell
+$ yarn serve
+```
+
+### OpenAPI Documentation
+
+To update the OpenAPI Documentation do the following:
+
+1. Update the `api/openapi.yaml` specification.  
+   It can be downloaded from a running OpenRemote instance, e.g.:  
+   `wget -O api/openapi.yaml http://localhost:8080/api/master/openapi.yaml`
+2. Replace the server URL in `api/openapi.yaml` from `/api/{realm}` to `https://demo.openremote.io/api/{realm}`, e.g.:  
+   `sed -i 's#/api/{realm}/#https://demo.openremote.io/api/{realm}/#g' api/openapi.yaml`
+3. Remove the previously generated OpenAPI documentation using:  
+   `yarn clean-api-docs all`
+4. Regenerate the OpenAPI documentation using:  
+   `yarn gen-api-docs all`
+
 ### Deployment
 
+The deployment is done automatically by a GitHub Actions workflow when commits are pushed to the "main" branch.
+
+It can also be done manually using the "deploy" command.
+
 Using SSH:
 
-```
+```shell
 $ USE_SSH=true yarn deploy
 ```
 
 Not using SSH:
 
-```
+```shell
 $ GIT_USER=<Your GitHub username> yarn deploy
 ```
 

api.mustache

@@ -0,0 +1,39 @@
+---
+id: {{{id}}}
+title: "{{{title}}}"
+description: "{{{frontMatter.description}}}"
+{{^api}}
+sidebar_label: Introduction
+{{/api}}
+{{#api}}
+sidebar_label: "{{{title}}}"
+{{/api}}
+{{^api}}
+sidebar_position: 0
+{{/api}}
+hide_title: true
+{{#api}}
+hide_table_of_contents: true
+{{/api}}
+{{#json}}
+api: {{{json}}}
+{{/json}}
+{{#api.method}}
+sidebar_class_name: "{{{api.method}}} api-method"
+{{/api.method}}
+{{#infoPath}}
+info_path: {{{infoPath}}}
+{{/infoPath}}
+custom_edit_url: null
+{{#frontMatter.proxy}}
+proxy: {{{frontMatter.proxy}}}
+{{/frontMatter.proxy}}
+{{#frontMatter.hide_send_button}}
+hide_send_button: true
+{{/frontMatter.hide_send_button}}
+{{#frontMatter.show_extensions}}
+show_extensions: true
+{{/frontMatter.show_extensions}}
+---
+
+{{{markdown}}}