docs: improve api docs (#5158)

* integrate docs into nav * generator for local use, production needs to be set by env * fix typo * local dev * docs: annotate the first user endpoints in the management api * docs: annotate the first user endpoints in the management api * docs: annotate the first user endpoints in the management api * docs: annotate the first user endpoints in the management api * docs: add header params * rewrite docs links and improve ci * tweak build command * fix path * Update docs/docusaurus.config.js Co-authored-by: Max Peintner <max@caos.ch> * fix docker * docs: add header params * docs: Add tags to management api. add some descriptions * docs: more descriptions * docs: more descriptions * docs: required fields * docs: example request * docs: example request * docs: example request * docs: example request * docs: example request * docs: user metadata requests * docs: user requests * docs: user requests * docs: user requests * docs: user requests * docs: change nav add first methods to authentication api * docs: auth api * docs: auth api * docs: auth api * docs: auth api * docs: auth api * docs: api sidenav * chore: use buf without docker * fix deploy * fix ci * fix vercel * docs: admin * docs: admin api docs * docs: admin api docs * docs: admin api docs * docs: admin api docs * docs: security * docs: security * docs: admin api * docs: change to env vars * docs: auth api * docs: remove assets, deprecated requests, menu * reworked page with PaloAltoNetworks/docusaurus-openapi-docs * works with the resolutions * fix broken build by adding assets again * add tags to menu * chore: improve build speed * no-minify * test ssr * ssr 20 * use lazy * increase mem * use default mem * change names * docs: remove assets, deprecated requests, menu * docs: management api * docs: management api * docs: management api * docs: sidebar * not the best word smithing but it is ;-) * more typos * merge main * fix some error * trial * update grpc gateway * trigger vercel build * docs: deprecated requests * docs: deprecated requests --------- Co-authored-by: Fabienne <fabienne.gerschwiler@gmail.com> Co-authored-by: Max Peintner <max@caos.ch>
2025-08-11 20:17:32 +00:00 · 2023-02-23 12:08:06 +01:00
parent 50728129ee
commit aa9518ac02
68 changed files with 7570 additions and 23543 deletions
--- a/docs/docusaurus.config.js
+++ b/docs/docusaurus.config.js
@@ -3,7 +3,7 @@ module.exports = {
  title: "ZITADEL Docs",
  trailingSlash: false,
  url: "https://zitadel.com",
-  baseUrl: "/docs/",
+  baseUrl: "/docs",
  onBrokenLinks: "throw",
  onBrokenMarkdownLinks: "warn",
  favicon: "img/favicon.ico",
@@ -204,10 +204,28 @@ module.exports = {
      respectPrefersColorScheme: true,
    },
  },
+  webpack: {
+    jsLoader: (isServer) => ({
+      loader: require.resolve('swc-loader'),
+      options: {
+        jsc: {
+          parser: {
+            syntax: 'typescript',
+            tsx: true,
+          },
+          target: 'es2017',
+        },
+        module: {
+          type: isServer ? 'commonjs' : 'es6',
+        },
+      },
+    }),
+  },
  presets: [
    [
-      "@docusaurus/preset-classic",
-      {
+      "classic",
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
        docs: {
          routeBasePath: "/",
          sidebarPath: require.resolve("./sidebars.js"),
@@ -215,14 +233,54 @@ module.exports = {
          showLastUpdateTime: true,
          editUrl: "https://github.com/zitadel/zitadel/edit/main/docs/",
          remarkPlugins: [require("mdx-mermaid")],
+          docLayoutComponent: "@theme/DocPage",
+          docItemComponent:  '@theme/ApiItem'
        },
        theme: {
          customCss: require.resolve("./src/css/custom.css"),
        },
-      },
+      })
    ],
+
  ],
  plugins: [
+    [
+      'docusaurus-plugin-openapi-docs',
+      {
+        id: "apiDocs",
+        docsPluginId: "classic",
+        config: {
+          auth: {
+            specPath: ".artifacts/openapi/zitadel/auth.swagger.json",
+            outputDir: "docs/apis/auth",
+            sidebarOptions: {
+              groupPathsBy: "tag",
+            },
+          },
+          mgmt: {
+            specPath: ".artifacts/openapi/zitadel/management.swagger.json",
+            outputDir: "docs/apis/mgmt",
+            sidebarOptions: {
+              groupPathsBy: "tag",
+            },
+          },
+          admin: {
+            specPath: ".artifacts/openapi/zitadel/admin.swagger.json",
+            outputDir: "docs/apis/admin",
+            sidebarOptions: {
+              groupPathsBy: "tag",
+            },
+          },
+          system: {
+            specPath: ".artifacts/openapi/zitadel/system.swagger.json",
+            outputDir: "docs/apis/system",
+            sidebarOptions: {
+              groupPathsBy: "tag",
+            },
+          }
+        }
+      },
+    ],
    require.resolve("docusaurus-plugin-image-zoom"),
    async function myPlugin(context, options) {
      return {
@@ -236,5 +294,5 @@ module.exports = {
      };
    },
  ],
-  themes: ["@saucelabs/theme-github-codeblock"],
+  themes: ["@saucelabs/theme-github-codeblock", "docusaurus-theme-openapi-docs"],
 };