feat(docs): autogenerate documentation from the API specs

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

microsite/docusaurus.config.ts

@@ -23,6 +23,7 @@ import type * as Preset from '@docusaurus/preset-classic';
 import { Config } from '@docusaurus/types';
 import RedirectPlugin from '@docusaurus/plugin-client-redirects';
 import { releases } from './releases';
+import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";
 
 const backstageTheme = themes.vsDark;
 backstageTheme.plain.backgroundColor = '#232323';
@@ -54,6 +55,14 @@ const PatchedRedirectPlugin: typeof RedirectPlugin = (ctx, opts) => {
   };
 };
 
+const defaultOpenApiOptions = {
+  hideSendButton: true,
+  sidebarOptions: {
+    groupPathsBy: 'tag',
+    categoryLinkSource: "tag",
+  },
+} satisfies OpenApiPlugin.Options
+
 const config: Config = {
   title: 'Backstage Software Catalog and Developer Platform',
   tagline: 'An open source framework for building developer portals',
@@ -110,6 +119,7 @@ const config: Config = {
                 },
               }
             : undefined),
+          docItemComponent: "@theme/ApiItem",
         },
         blog: {
           path: 'blog',
@@ -266,7 +276,27 @@ const config: Config = {
         ratingMode: 'stars',
       },
     ],
+    [
+      'docusaurus-plugin-openapi-docs',
+      {
+        id: "api", // plugin id
+        docsPluginId: "classic", // configured for preset-classic
+        config: {
+          catalog: {
+            ...defaultOpenApiOptions,
+            specPath: "../plugins/catalog-backend/src/schema/openapi.yaml",
+            outputDir: "../docs/features/software-catalog/api",
+          } satisfies OpenApiPlugin.Options,
+          search: {
+            ...defaultOpenApiOptions,
+            specPath: "../plugins/search-backend/src/schema/openapi.yaml",
+            outputDir: "../docs/features/search/api",
+          } satisfies OpenApiPlugin.Options,
+        }
+      },
+    ]
   ],
+  themes: ["docusaurus-theme-openapi-docs"],
   themeConfig: {
     colorMode: {
       defaultMode: 'dark',

microsite/package.json

@@ -7,6 +7,7 @@
     "build": "node scripts/pre-build.js && docusaurus build",
     "deploy": "docusaurus deploy",
     "docusaurus": "docusaurus",
+    "generate-openapi-docs": "yarn docusaurus clean-api-docs all && yarn docusaurus gen-api-docs all",
     "prettier:check": "prettier --check .",
     "prettier:fix": "prettier --write .",
     "publish-gh-pages": "docusaurus-publish",
@@ -18,6 +19,9 @@
     "write-translations": "docusaurus-write-translations"
   },
   "prettier": "@backstage/cli/config/prettier",
+  "resolutions": {
+    "node-polyfill-webpack-plugin": "^3.0.0"
+  },
   "dependencies": {
     "@docusaurus/core": "^3.1.1",
     "@docusaurus/plugin-client-redirects": "^3.1.1",
@@ -26,8 +30,10 @@
     "@mdx-js/react": "^3.0.0",
     "@swc/core": "^1.3.46",
     "clsx": "^2.0.0",
+    "docusaurus-plugin-openapi-docs": "^4.3.0",
     "docusaurus-plugin-sass": "^0.2.3",
     "docusaurus-pushfeedback": "^1.0.0",
+    "docusaurus-theme-openapi-docs": "^4.3.0",
     "luxon": "^3.0.0",
     "prism-react-renderer": "^2.1.0",
     "react": "^18.0.2",

microsite/sidebars.js

@@ -1,6 +1,17 @@
-const { releases } = require('./releases');
+import { releases } from './releases';
 
-module.exports = {
+function tryToLoadCustomSidebar(ref){
+  try{
+    return require(ref)
+  } catch (e) {
+    return []
+  }
+}
+
+const catalogSidebar = tryToLoadCustomSidebar("../docs/features/software-catalog/api/sidebar.ts")
+const searchSidebar = tryToLoadCustomSidebar("../docs/features/search/api/sidebar.ts")
+
+export default {
   docs: {
     Overview: [
       'overview/what-is-backstage',
@@ -136,6 +147,19 @@ module.exports = {
           'features/search/search-overview',
           'features/search/getting-started',
           'features/search/concepts',
+          {
+            type: "category",
+            label: "API",
+            link: searchSidebar.length > 0 ? {
+              type: "generated-index",
+              title: "Search API",
+              slug: "/category/search-api",
+            } : {
+              type: "doc",
+              id: "openapi/generated-docs/404",
+            },
+            items: searchSidebar,
+          },
           'features/search/architecture',
           'features/search/search-engines',
           'features/search/collators',
@@ -158,7 +182,19 @@ module.exports = {
           'features/software-catalog/extending-the-model',
           'features/software-catalog/external-integrations',
           'features/software-catalog/catalog-customization',
-          'features/software-catalog/software-catalog-api',
+          {
+            type: "category",
+            label: "API",
+            link: catalogSidebar.length > 0 ? {
+              type: "generated-index",
+              title: "Catalog API",
+              slug: "/category/catalog-api",
+            }: {
+              type: "doc",
+              id: "openapi/generated-docs/404",
+            },
+            items: catalogSidebar,
+          },
           'features/software-catalog/creating-the-catalog-graph',
           'features/software-catalog/faq',
         ],