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

This PR is a recreation of #109 .

## Description

The goal of this PR is to enrich our docusaurus site, by adding
[`docusaurus-openapi-docs`](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs)
and using it to embed OpenAPI/Swagger generated content.

In this PR, we are vendoring the OpenAPI (YAML) files, which are found
in OpenTDF (
[here](https://github.com/opentdf/platform/tree/main/docs/openapi) ).

## Reviewing this PR

To generate the site for a typical deployment, build and start the site
as follows:

```
# Set env var, or simply skip it
export BUILD_OPENAPI_SAMPLES=0
rm -rf docs/SDK-OpenAPI/ docs/SDK-Samples/ specs-processed/
npm run gen-api-docs-clean && npm run gen-api-docs-all
npm run start
```


To generate the site including "art of the possible" (petstore &
bookstore examples), build and start the site as follows:

```
export BUILD_OPENAPI_SAMPLES=1 
rm -rf docs/SDK-OpenAPI/ docs/SDK-Samples/ specs-processed/
npm run gen-api-docs-clean && npm run gen-api-docs-all
npm run start
```

### Video 2 (loom)

https://www.loom.com/share/522b0eb6b2d34793ba555b1ca3a31722

### Video 1 

<details><summary>Click to show</summary>
<p>



https://github.com/user-attachments/assets/25f22aed-5ba5-4a4f-bd76-17acc5daf2df


</p>
</details> 
### To-do

- [ ] Determine if we need to run `npm run gen-api-docs-all`
(explicitly) for CI and/or production builds. In other words, does this
happen automatically?

### Defer / New Jira tickets

- [x] Revert [Disable false-positive
machine](d228655)
/ figure out the right way to tune Vale ➡️ recommend a new Jira ticket /
PR
- [ ] Use remote OpenAPI definition files? ➡️ recommend a new Jira
ticket / PR

### Vale

If I were king for a day, I'd just remove this tool.  

<details><summary>It's pretty unclear (to me) how to improve the
configuration quality</summary>
<p>




<img width="1495" alt="image"
src="https://github.com/user-attachments/assets/6e22dcc3-7b2e-4c47-bed7-040ee58137d9"
/>



</p>
</details> 


<details><summary>It's complaining about files that are untouched /
unmodified in this PR</summary>
<p>


<img width="1495" alt="image"
src="https://github.com/user-attachments/assets/c2908677-e306-4d74-8511-ac1bf1652715"
/>


</p>
</details> 

<details><summary>And some part of it's machinery / reviewdog thinks we
have too much content to process... which seems tricky, because clearly
we will have large diffs if we intend to version generated
content.</summary>
<p>




<img width="1495" alt="image"
src="https://github.com/user-attachments/assets/2ee4786d-24af-45ba-bbaa-2acecfafd97f"
/>



</p>
</details>

Author: b-long

.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;