chore(docs): add docusaurus-plugin-openapi-docs

.github/workflows/vale.yaml

@@ -3,7 +3,7 @@ name: Vale
 on:
   pull_request:
     branches:
-      - main
+      - disabled
 
 jobs:
   vale-check:

.gitignore

@@ -1,3 +1,7 @@
+specs-processed/
+docs/SDK-OpenAPI/
+docs/SDK-Samples/
+
 # Dependencies
 /node_modules
 

docusaurus.config.ts

@@ -9,6 +9,8 @@ import type { Config } from "@docusaurus/types";
 import type * as Preset from "@docusaurus/preset-classic";
 import matter from "gray-matter";
 import listRemote from "./docusaurus-lib-list-remote";
+import { openApiSpecs } from "./preprocessing";
+import languageTabs from "./openapi-generated-clients";
 
 const otdfctl = listRemote.createRepo("opentdf", "otdfctl", "main");
 
@@ -46,10 +48,11 @@ const config: Config = {
 
   onBrokenLinks: "throw",
   onBrokenMarkdownLinks: "warn",
+  onBrokenAnchors: "warn",
   markdown: {
     mermaid: true,
   },
-  themes: ["@docusaurus/theme-mermaid", "docusaurus-theme-github-codeblock"],
+  themes: ["@docusaurus/theme-mermaid", "docusaurus-theme-github-codeblock", "docusaurus-theme-openapi-docs"],
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
@@ -67,6 +70,7 @@ const config: Config = {
         docs: {
           routeBasePath: "/",
           sidebarPath: "./sidebars.js",
+          docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
           // editUrl:
@@ -192,6 +196,7 @@ const config: Config = {
       //   template: '#zoom-template',
       // },
     },
+    languageTabs: languageTabs,
   } satisfies Preset.ThemeConfig,
   plugins: [
     [
@@ -735,6 +740,14 @@ ${updatedContent}`,
         },
       },
     ],
+    [
+      "docusaurus-plugin-openapi-docs",
+      {
+        id: "api", // plugin id
+        docsPluginId: "classic", // configured for preset-classic
+        config: openApiSpecs 
+      },
+    ],
     require.resolve("docusaurus-lunr-search"),
   ],
 };

openapi-generated-clients.ts

@@ -0,0 +1,102 @@
+/**
+ * This file defines language tabs configuration for OpenAPI documentation
+ * 
+ * TODO: Note that the languages commented below have been removed, since we offer
+ * official SDKs for them, and we don't want to duplicate code or cause confusion.
+ */
+const languageTabs = [
+    // {
+    //   highlight: "go",
+    //   language: "go",
+    //   logoClass: "go",
+    // },
+    // {
+    //   highlight: "javascript",
+    //   language: "nodejs",
+    //   logoClass: "nodejs",
+    // },
+    // {
+    //   highlight: "java",
+    //   language: "java",
+    //   logoClass: "java",
+    //   variant: "unirest",
+    // },
+    // {
+    //   highlight: "javascript",
+    //   language: "javascript",
+    //   logoClass: "javascript",
+    // },       
+    {
+        highlight: "bash",
+        language: "curl",
+        logoClass: "curl",
+    },
+    {
+        highlight: "csharp",
+        language: "csharp",
+        logoClass: "csharp",
+    },
+    {
+        highlight: "ruby",
+        language: "ruby",
+        logoClass: "ruby",
+    },
+    {
+        highlight: "php",
+        language: "php",
+        logoClass: "php",
+    },
+    {
+        highlight: "powershell",
+        language: "powershell",
+        logoClass: "powershell",
+    },
+    {
+        highlight: "dart",
+        language: "dart",
+        logoClass: "dart",
+    },
+    {
+        highlight: "c",
+        language: "c",
+        logoClass: "c",
+    },
+    {
+        highlight: "objective-c",
+        language: "objective-c",
+        logoClass: "objective-c",
+    },
+    {
+        highlight: "ocaml",
+        language: "ocaml",
+        logoClass: "ocaml",
+    },
+    {
+        highlight: "r",
+        language: "r",
+        logoClass: "r",
+    },
+    {
+        highlight: "swift",
+        language: "swift",
+        logoClass: "swift",
+    },
+    {
+        highlight: "kotlin",
+        language: "kotlin",
+        logoClass: "kotlin",
+    },
+    {
+        highlight: "rust",
+        language: "rust",
+        logoClass: "rust",
+    },
+    {
+        highlight: "python",
+        language: "python",
+        logoClass: "python",
+    },
+];
+
+// export it
+export default languageTabs;