Devrel 1673

.gitignore

@@ -33,6 +33,7 @@ yarn.lock
 /docs/api/beta
 /docs/api/iiq
 /docs/api/nerm/*
+/docs/api/v2024/*
 !/docs/api/nerm/authentication.md
 !/docs/api/nerm/pagination-metadata-filtering.md
 !/docs/api/nerm/getting-started.md

createApiPageMD.ts

@@ -0,0 +1,105 @@
+import { createAuthentication } from "docusaurus-plugin-openapi-docs/src/markdown/createAuthentication";
+import { createAuthorization } from "docusaurus-plugin-openapi-docs/src/markdown/createAuthorization";
+import { createCallbacks } from "docusaurus-plugin-openapi-docs/src/markdown/createCallbacks";
+import { createContactInfo } from "docusaurus-plugin-openapi-docs/src/markdown/createContactInfo";
+import { createDeprecationNotice } from "docusaurus-plugin-openapi-docs/src/markdown/createDeprecationNotice";
+import { createDescription } from "docusaurus-plugin-openapi-docs/src/markdown/createDescription";
+import { createDownload } from "docusaurus-plugin-openapi-docs/src/markdown/createDownload";
+import { createHeading } from "docusaurus-plugin-openapi-docs/src/markdown/createHeading";
+import { createLicense } from "docusaurus-plugin-openapi-docs/src/markdown/createLicense";
+import { createLogo } from "docusaurus-plugin-openapi-docs/src/markdown/createLogo";
+import { createMethodEndpoint } from "docusaurus-plugin-openapi-docs/src/markdown/createMethodEndpoint";
+import { createParamsDetails } from "docusaurus-plugin-openapi-docs/src/markdown/createParamsDetails";
+import { createRequestBodyDetails } from "docusaurus-plugin-openapi-docs/src/markdown/createRequestBodyDetails";
+import { createRequestHeader } from "docusaurus-plugin-openapi-docs/src/markdown/createRequestHeader";
+import { createNodes } from "docusaurus-plugin-openapi-docs/src/markdown/createSchema";
+import { createStatusCodes } from "docusaurus-plugin-openapi-docs/src/markdown/createStatusCodes";
+import { createTermsOfService } from "docusaurus-plugin-openapi-docs/src/markdown/createTermsOfService";
+import { createVendorExtensions } from "docusaurus-plugin-openapi-docs/src/markdown/createVendorExtensions";
+import { createVersionBadge } from "docusaurus-plugin-openapi-docs/src/markdown/createVersionBadge";
+import { create, greaterThan, lessThan, render } from "docusaurus-plugin-openapi-docs/src/markdown/utils";
+import {
+  ContactObject,
+  LicenseObject,
+  MediaTypeObject,
+  SecuritySchemeObject,
+} from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import {
+  ApiPageMetadata,
+  InfoPageMetadata,
+  SchemaPageMetadata,
+  TagPageMetadata,
+} from "docusaurus-plugin-openapi-docs/src/types";
+
+interface RequestBodyProps {
+  title: string;
+  body: {
+    content?: {
+      [key: string]: MediaTypeObject;
+    };
+    description?: string;
+    required?: boolean;
+  };
+}
+
+export function createApiPageMD({
+  title,
+  api: {
+    deprecated,
+    "x-deprecated-description": deprecatedDescription,
+    description,
+    method,
+    path,
+    extensions,
+    parameters,
+    requestBody,
+    responses,
+    callbacks,
+  },
+  infoPath,
+  frontMatter,
+}: ApiPageMetadata) {
+  return render([
+    `import ApiTabs from "@theme/ApiTabs";\n`,
+    `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
+    `import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";\n`,
+    `import SecuritySchemes from "@theme/ApiExplorer/SecuritySchemes";\n`,
+    `import MimeTabs from "@theme/MimeTabs";\n`,
+    `import ParamsItem from "@theme/ParamsItem";\n`,
+    `import ResponseSamples from "@theme/ResponseSamples";\n`,
+    `import SchemaItem from "@theme/SchemaItem";\n`,
+    `import SchemaTabs from "@theme/SchemaTabs";\n`,
+    `import Markdown from "@theme/Markdown";\n`,
+    `import Heading from "@theme/Heading";\n`,
+    `import OperationTabs from "@theme/OperationTabs";\n`,
+    `import TabItem from "@theme/TabItem";\n\n`,
+    createHeading(title),
+    createMethodEndpoint(method, path),
+    infoPath && createAuthorization(infoPath),
+    frontMatter.show_extensions
+      ? createVendorExtensions(extensions)
+      : undefined,
+    createDeprecationNotice({ deprecated, description: deprecatedDescription }),
+    createExperimentalNotice(parameters),
+    createDescription(description),
+    requestBody || parameters ? createRequestHeader("Request") : undefined,
+    createParamsDetails({ parameters, type: "path" }),
+    createParamsDetails({ parameters, type: "query" }),
+    createParamsDetails({ parameters, type: "header" }),
+    createParamsDetails({ parameters, type: "cookie" }),
+    createRequestBodyDetails({
+      title: "Body",
+      body: requestBody,
+    } as RequestBodyProps),
+    createStatusCodes({ responses }),
+    createCallbacks({ callbacks }),
+  ]);
+}
+
+function createExperimentalNotice(parameters){
+        if (parameters && parameters.some(element => element.in === 'header' && element.name === 'X-SailPoint-Experimental')) {
+            return ":::warning experimental\n\nThis API is currently in an experimental state. The API is subject to change based on feedback and further testing. You must include the X-SailPoint-Experimental header and set it to `true` to use this endpoint.\n\n:::\n\n";
+        }
+        // Return an empty string if the condition is not met
+        return "";
+}

navbar.js

@@ -15,7 +15,16 @@ module.exports = {
         {label: 'IdentityIQ', to: '/docs/iiq'},
       ],
     },
-
+    {
+      type: 'dropdown',
+      label: 'API Specifications',
+      position: 'left',
+      items: [
+        {label: 'Identity Security Cloud', to: '/docs/api/v2024'},
+        {label: 'IdentityIQ', to: '/docs/api/iiq'},
+        {label: 'NERM', to: '/docs/api/nerm/v1'},
+      ],
+    },
     {
       type: 'dropdown',
       label: 'Community',

package.json

@@ -16,8 +16,8 @@
     "clean-api-docs": "docusaurus clean-api-docs",
     "gen-api-docs:version": "docusaurus gen-api-docs:version",
     "clean-api-docs:version": "docusaurus clean-api-docs:version",
-    "gen-api-docs-all": "docusaurus gen-api-docs idn_v3 --plugin-id idn-api && docusaurus gen-api-docs idn_beta --plugin-id idn-api && docusaurus gen-api-docs iiq --plugin-id iiq-api && docusaurus gen-api-docs nerm --plugin-id nerm-api",
-    "clean-api-docs-all": "docusaurus clean-api-docs idn_v3 --plugin-id idn-api && docusaurus clean-api-docs idn_beta --plugin-id idn-api && docusaurus clean-api-docs iiq --plugin-id iiq-api && docusaurus clean-api-docs nerm --plugin-id nerm-api",
+    "gen-api-docs-all": "docusaurus gen-api-docs:version isc_versioned:all --plugin-id isc-api && docusaurus gen-api-docs isc_versioned --plugin-id isc-api && docusaurus gen-api-docs iiq --plugin-id iiq-api && docusaurus gen-api-docs nerm --plugin-id nerm-api",
+    "clean-api-docs-all": "docusaurus clean-api-docs isc_versioned --plugin-id isc-api && docusaurus clean-api-docs:version isc_versioned:all --plugin-id isc-api && docusaurus clean-api-docs iiq --plugin-id iiq-api && docusaurus clean-api-docs nerm --plugin-id nerm-api",
     "rebuild-docs": "npm run clean-api-docs-all && npm run gen-api-docs-all"
   },
   "dependencies": {
@@ -34,7 +34,7 @@
     "autoprefixer": "^10.4.13",
     "classnames": "^2.3.2",
     "clsx": "^2.0.0",
-    "docusaurus-plugin-openapi-docs": "^3.0.1",
+    "docusaurus-plugin-openapi-docs": "^0.0.0-761",
     "docusaurus-theme-openapi-docs": "^3.0.1",
     "docusaurus2-dotenv": "^1.4.0",
     "esbuild-loader": "^2.20.0",

plugins.js

@@ -1,3 +1,5 @@
+const {createApiPageMD} = require('./createApiPageMD');
+
 module.exports = [
   [
     'docusaurus2-dotenv',
@@ -1619,6 +1621,52 @@ module.exports = [
       },
     },
   ],
+  [
+    'docusaurus-plugin-openapi-docs',
+    {
+      id: 'isc-api',
+      docsPluginId: 'isc',
+      config: {
+        isc_versioned: {
+          specPath: 'static/api-specs/idn/sailpoint-api.v2024.yaml',
+          outputDir: 'docs/api/v2024',
+          sidebarOptions: {
+            groupPathsBy: 'tag',
+            categoryLinkSource: 'tag',
+          },
+          version: 'v2024',
+          label: 'v2024',
+          baseUrl: '/docs/api/v2024',
+          template: 'api.mustache',
+          markdownGenerators: {
+            createApiPageMD,
+          },
+          versions: {
+            // v2025: {
+            //   specPath: 'static/api-specs/idn/sailpoint-api.v2025.yaml',
+            //   outputDir: 'docs/api/v2025',
+            //   label: 'v2025',
+            //   baseUrl: '/docs/api/v2025',
+            // },
+            v3: {
+              specPath: 'static/api-specs/idn/sailpoint-api.v3.yaml',
+              outputDir: 'docs/api/v3',
+              downloadUrl: 'https://raw.githubusercontent.com/sailpoint-oss/api-specs/main/dereferenced/deref-sailpoint-api.v3.yaml',
+              label: 'v3',
+              baseUrl: '/docs/api/v3',
+            },
+            beta: {
+              specPath: 'static/api-specs/idn/sailpoint-api.beta.yaml',
+              outputDir: 'docs/api/beta',
+              downloadUrl: 'https://raw.githubusercontent.com/sailpoint-oss/api-specs/main/dereferenced/deref-sailpoint-api.beta.yaml',
+              label: 'Beta',
+              baseUrl: '/docs/api/beta',
+            },
+          },
+        },
+      },
+    },
+  ],
   [
     'docusaurus-plugin-openapi-docs',
     {
@@ -1660,7 +1708,7 @@ module.exports = [
     },
   ],
   [
-    "@gracefullight/docusaurus-plugin-microsoft-clarity",
-    { projectId: "naher5vlxx" },
+    '@gracefullight/docusaurus-plugin-microsoft-clarity',
+    {projectId: 'naher5vlxx'},
   ],
 ];