Add API Reference (#253)

Author: AHGIJMKLKKZNPJKQR

docs/api/reference.md

@@ -23,7 +23,7 @@ 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)
+[Server REST API Reference](/api/rest)
 
 ### Protobufs
 

docs/how-to/backend/server-setup.mdx

@@ -14,37 +14,45 @@ Install the SDK for the language of your choice. We provide libraries for [**Nod
 It's also possible to use the bare REST API, in this case you can skip this step.
 
 <Tabs groupId="sdk">
-  <TabItem value="npm" label="NPM">
+  <TabItem value="npm" label="npm">
 
     ```bash
     npm install @fishjam-cloud/js-server-sdk
     ```
 
   </TabItem>
 
-  <TabItem value="yarn" label="YARN">
+  <TabItem value="yarn" label="yarn">
 
     ```bash
     yarn add @fishjam-cloud/js-server-sdk
     ```
 
   </TabItem>
 
-  <TabItem value="pip" label="PIP">
+  <TabItem value="pip" label="pip">
 
     ```bash
     pip install fishjam-server-sdk
     ```
 
   </TabItem>
 
-  <TabItem value="poetry" label="POETRY">
+  <TabItem value="poetry" label="poetry">
 
     ```bash
     poetry add fishjam-server-sdk
     ```
 
   </TabItem>
+  
+  <TabItem value="uv" label="uv">
+
+    ```bash
+    uv add fishjam-server-sdk
+    ```
+
+  </TabItem>
 </Tabs>
 
 ## Setup your client

docs/tutorials/backend-quick-start.mdx

@@ -114,6 +114,14 @@ A simple backend server that can create rooms, add peers, and generate tokens fo
         ```
 
       </TabItem>
+
+      <TabItem value="uv" label="uv">
+
+        ```bash
+        uv add fishjam-server-sdk
+        ```
+
+      </TabItem>
     </Tabs>
 
   </TabItem>
@@ -395,6 +403,14 @@ Build a simple HTTP endpoint that your client apps can call:
         ```
 
       </TabItem>
+
+      <TabItem value="uv" label="uv">
+
+        ```bash
+        uv add fastapi[standard]
+        ```
+
+      </TabItem>
     </Tabs>
 
   </TabItem>

docusaurus.config.ts

@@ -1,10 +1,10 @@
 import type { Config } from "@docusaurus/types";
 import type * as Preset from "@docusaurus/preset-classic";
 import type { UserThemeConfig as DocSearchThemeConfig } from "@docsearch/docusaurus-adapter";
+import type { ScalarOptions } from "@scalar/docusaurus";
 import { BundledLanguage, bundledLanguages } from "shiki";
 import type { MDXPlugin } from "@docusaurus/mdx-loader";
 import rehypeShiki, { RehypeShikiOptions } from "@shikijs/rehype";
-import { removeTwoslashNotations } from "twoslash";
 import {
   transformerMetaHighlight,
   transformerNotationDiff,
@@ -241,6 +241,21 @@ const config: Config = {
         src: "img/logo.svg",
       },
       items: [
+        {
+          type: "doc",
+          docId: "index",
+          label: "Docs",
+          position: "left",
+        },
+        {
+          to: "/api/rest",
+          label: "API Reference",
+          position: "left",
+        },
+        {
+          type: "docsVersionDropdown",
+          position: "right",
+        },
         {
           href: "https://fishjam.io/app/",
           label: "Fishjam Dashboard",
@@ -251,9 +266,6 @@ const config: Config = {
           label: "GitHub",
           position: "right",
         },
-        {
-          type: "docsVersionDropdown",
-        },
       ],
     },
     docsearch: {
@@ -313,6 +325,23 @@ const config: Config = {
   plugins: [
     ["@docusaurus/plugin-client-redirects", { createRedirects }],
     "@docsearch/docusaurus-adapter",
+    [
+      "@scalar/docusaurus",
+      {
+        label: "Server REST API",
+        route: "/api/rest",
+        showNavLink: false,
+        configuration: {
+          url: "/docs/api/fishjam-server-openapi.yaml",
+          hideSearch: true,
+          persistAuth: true,
+          defaultOpenFirstTag: false,
+          authentication: {
+            preferredSecurityScheme: "management_token",
+          },
+        },
+      } as ScalarOptions,
+    ],
     [
       "docusaurus-plugin-typedoc",
       {

package.json

@@ -31,11 +31,13 @@
     "@docusaurus/preset-classic": "^3.10.0",
     "@docusaurus/remark-plugin-npm2yarn": "^3.10.0",
     "@docusaurus/theme-mermaid": "^3.10.0",
+    "@docusaurus/utils": "^3.10.0",
     "@fastify/env": "^5.0.2",
     "@fishjam-cloud/js-server-sdk": "link:./packages/js-server-sdk/packages/js-server-sdk",
     "@fishjam-cloud/react-client": "link:./packages/web-client-sdk/packages/react-client",
     "@fishjam-cloud/react-native-client": "link:./packages/web-client-sdk/packages/mobile-client",
     "@mdx-js/react": "^3.1.0",
+    "@scalar/docusaurus": "^0.8.5",
     "@shikijs/rehype": "^3.6.0",
     "@shikijs/transformers": "^3.6.0",
     "@swmansion/smelter": "^0.2.1",

src/css/custom.css

@@ -28,15 +28,19 @@
   --ifm-color-primary-lightest: #4fddbf;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
 }
+
 html[data-theme="light"] body {
   color: #221f1c;
 }
+
 html[data-theme="light"] footer.footer {
   background-color: #fcf4e4;
 }
+
 html[data-theme="light"] nav.navbar--fixed-top {
   background-color: #fcf4e4;
 }
+
 html[data-theme="light"] header.heroBanner_src-pages-index-module {
   background-color: #9bdcfb;
   color: #221f1c;
@@ -64,6 +68,10 @@ html[data-theme="light"] header.heroBanner_src-pages-index-module {
   vertical-align: middle;
 }
 
+.scalar-api-reference .badge {
+  text-transform: unset;
+}
+
 .badge--web {
   background-color: #3578e5;
   color: white;
@@ -114,3 +122,28 @@ extra spacing keeps it from overlapping with cookies button */
 }
 
 @import url("./_shiki.css");
+
+/* Align the Scalar API reference typography with the rest of the docs. */
+:root {
+  --scalar-font-size-1: var(--ifm-h3-font-size);
+  --scalar-font-size-2: var(--ifm-h4-font-size);
+  --scalar-font-size-3: 0.9375rem;
+  --scalar-font-size-4: 0.9rem;
+  --scalar-font-size-5: 0.85rem;
+  --scalar-font-size-6: 0.8rem;
+  --scalar-font-size-7: 0.75rem;
+
+  --scalar-paragraph: 0.9375rem;
+  --scalar-small: 0.9rem;
+  --scalar-mini: 0.75rem;
+
+  --scalar-heading-1: var(--ifm-h1-font-size);
+  --scalar-heading-2: var(--ifm-h2-font-size);
+  --scalar-heading-3: var(--ifm-h3-font-size);
+  --scalar-heading-4: var(--ifm-h4-font-size);
+  --scalar-heading-5: var(--ifm-h5-font-size);
+  --scalar-heading-6: var(--ifm-h6-font-size);
+
+  --scalar-font: var(--ifm-font-family-base);
+  --scalar-font-code: var(--ifm-font-family-monospace);
+}

src/theme/NavbarItem/index.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { useLocation } from "@docusaurus/router";
+import useBaseUrl from "@docusaurus/useBaseUrl";
+import OriginalNavbarItem from "@theme-original/NavbarItem";
+
+type NavbarItemProps = React.ComponentProps<typeof OriginalNavbarItem>;
+
+export default function NavbarItemWrapper(
+  props: NavbarItemProps,
+): React.JSX.Element | null {
+  const { pathname } = useLocation();
+  const apiReferenceUrl = useBaseUrl("/api/rest");
+  const isDocsVersionDropdown = props.type === "docsVersionDropdown";
+  const isApiReferencePage = pathname.startsWith(apiReferenceUrl);
+
+  // The Scalar REST reference is unversioned, so we hide the version dropdown
+  if (isDocsVersionDropdown && isApiReferencePage) {
+    return null;
+  }
+
+  return <OriginalNavbarItem {...props} />;
+}