Fce 1833 document api (#158)

Added API Reference page and a script to fetch the latest api
documentation versions from relevant repositories.

Resolves #135

Author: roznawsk

.cspell.json

@@ -16,7 +16,8 @@
     ".git/**",
     "*.lock",
     "yarn.lock",
-    "package-lock.json"
+    "package-lock.json",
+    "api/**"
   ],
   "ignoreRegExpList": ["JSXComment", "/^\\s*```[\\s\\S]*?^\\s*```/gm"],
 

.github/workflows/docs.yaml

@@ -30,6 +30,9 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.SUBMODULES_TOKEN }}
+          submodules: recursive
       # 👇 Build steps
       - name: Set up Node.js
         uses: actions/setup-node@v4

.github/workflows/static_check.yml

@@ -8,7 +8,8 @@ jobs:
       - name: checkout
         uses: actions/checkout@v4
         with:
-          submodules: "recursive"
+          token: ${{ secrets.SUBMODULES_TOKEN }}
+          submodules: recursive
       - name: init and update submodules
         run: git submodule update --init --recursive
       - name: Set up Node.js

.gitmodules

@@ -7,3 +7,12 @@
 [submodule "packages/js-server-sdk"]
 	path = packages/js-server-sdk
 	url = https://github.com/fishjam-cloud/js-server-sdk.git
+[submodule "api/protos"]
+	path = api/protos
+	url = https://github.com/fishjam-cloud/protos
+[submodule "api/fishjam-server"]
+	path = api/fishjam-server
+	url = git@github.com:fishjam-cloud/fishjam.git
+[submodule "api/room-manager"]
+	path = api/room-manager
+	url = git@github.com:fishjam-cloud/room-manager.git

.prettierignore

@@ -1,4 +1,6 @@
 build/*
 node_modules/*
 .yarn/*
-packages/*
+packages/*
+api/**
+versioned_docs/*/api/**

api/fishjam-server

@@ -0,0 +1,49 @@
+---
+type: reference
+---
+
+# Reference
+
+Describes APIs for direct interaction with Fishjam.
+
+Fishjam publishes documentation for the Sandbox API and Fishjam Server APIs.
+
+## Sandbox API
+
+[Sandbox API OpenAPI](https://github.com/fishjam-cloud/documentation/tree/main/static/api/room-manager-openapi.yaml)
+
+See also: [What is the Sandbox API?](/explanation/sandbox-api-concept)
+
+## Server
+
+Fishjam Server provides a REST API for managing rooms and peers, and
+[Protobufs](https://protobuf.dev) for
+receiving structured live updates from the server.
+The notifications can be configured using Webhook or Websocket.
+
+### REST API
+
+[Server OpenAPI](https://github.com/fishjam-cloud/documentation/tree/main/static/api/fishjam-server-openapi.yaml)
+
+### Protobufs
+
+[Server Protobufs](https://github.com/fishjam-cloud/documentation/tree/main/static/api/server_notifications.proto)
+
+#### Webhook
+
+When using webhooks for receiving notifications, the `webhookUrl` must be passed
+in the `RoomConfig` options when creating a room.
+
+The HTTP POST to the `webhookUrl` uses "application/x-protobuf" content type.
+The body is binary data, that represents encoded `ServerMessage`.
+
+For more information see also [server setup documentation](/how-to/backend/server-setup#webhooks)
+
+#### Websocket
+
+After opening the Websocket connection to
+`https://fishjam.io/api/v1/connect/{fishjamId}/socket/server/websocket`,
+the first message that must be sent is an `AuthRequest`,
+with a valid Management Token.
+
+Next, you can should subscribe to notifications by sending `SubscribeRequest` event with `SERVER_NOTIFICATION` event type.

api/protos

@@ -37,24 +37,27 @@ function injectTypeDocSidebar(items) {
       return {
         ...item,
         items: [
-          {
-            type: "category",
-            label: "React Native SDK",
-            link: { type: "doc", id: "api/mobile/index" },
-            items: require("./docs/api/mobile/typedoc-sidebar.cjs"),
-          },
-          {
-            type: "category",
-            label: "React SDK",
-            link: { type: "doc", id: "api/web/index" },
-            items: require("./docs/api/web/typedoc-sidebar.cjs"),
-          },
-          {
-            type: "category",
-            label: "Server SDK for JS",
-            link: { type: "doc", id: "api/server/index" },
-            items: require("./docs/api/server/typedoc-sidebar.cjs"),
-          },
+          ...[
+            {
+              type: "category",
+              label: "React Native SDK",
+              link: { type: "doc", id: "api/mobile/index" },
+              items: require("./docs/api/mobile/typedoc-sidebar.cjs"),
+            },
+            {
+              type: "category",
+              label: "React SDK",
+              link: { type: "doc", id: "api/web/index" },
+              items: require("./docs/api/web/typedoc-sidebar.cjs"),
+            },
+            {
+              type: "category",
+              label: "Server SDK for JS",
+              link: { type: "doc", id: "api/server/index" },
+              items: require("./docs/api/server/typedoc-sidebar.cjs"),
+            },
+          ],
+          ...item.items.filter((element) => element.type == "doc"),
         ],
       };
     }