docusaurus-plugin-openapi-docs 4.0.1 → 4.2.0

package/lib/openapi/openapi.js

@@ -21,8 +21,9 @@ const uniq_1 = __importDefault(require("lodash/uniq"));
 const openapi_to_postmanv2_1 = __importDefault(require("openapi-to-postmanv2"));
 const postman_collection_1 = __importDefault(require("postman-collection"));
 const createRequestExample_1 = require("./createRequestExample");
-const loadAndResolveSpec_1 = require("./utils/loadAndResolveSpec");
 const index_1 = require("../index");
+const createResponseExample_1 = require("./createResponseExample");
+const loadAndResolveSpec_1 = require("./utils/loadAndResolveSpec");
 /**
  * Convenience function for converting raw JSON to a Postman Collection object.
  */
@@ -61,7 +62,7 @@ async function createPostmanCollection(openapiData) {
     return await jsonToCollection(data);
 }
 function createItems(openapiData, options, sidebarOptions) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6, _7;
     // TODO: Find a better way to handle this
     let items = [];
     const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase();
@@ -212,15 +213,15 @@ function createItems(openapiData, options, sidebarOptions) {
         }
     }
     // Gather x-webhooks endpoints
-    for (let [path, pathObject] of Object.entries((_p = openapiData["x-webhooks"]) !== null && _p !== void 0 ? _p : {})) {
+    for (let [path, pathObject] of Object.entries((_q = (_p = openapiData["x-webhooks"]) !== null && _p !== void 0 ? _p : openapiData["webhooks"]) !== null && _q !== void 0 ? _q : {})) {
         path = "webhook";
         const { $ref, description, parameters, servers, summary, ...rest } = pathObject;
         for (let [method, operationObject] of Object.entries({ ...rest })) {
             method = "event";
-            const title = (_r = (_q = operationObject.summary) !== null && _q !== void 0 ? _q : operationObject.operationId) !== null && _r !== void 0 ? _r : "Missing summary";
+            const title = (_s = (_r = operationObject.summary) !== null && _r !== void 0 ? _r : operationObject.operationId) !== null && _s !== void 0 ? _s : "Missing summary";
             if (operationObject.description === undefined) {
                 operationObject.description =
-                    (_t = (_s = operationObject.summary) !== null && _s !== void 0 ? _s : operationObject.operationId) !== null && _t !== void 0 ? _t : "";
+                    (_u = (_t = operationObject.summary) !== null && _t !== void 0 ? _t : operationObject.operationId) !== null && _u !== void 0 ? _u : "";
             }
             const baseId = operationObject.operationId
                 ? (0, kebabCase_1.default)(operationObject.operationId)
@@ -232,10 +233,10 @@ function createItems(openapiData, options, sidebarOptions) {
                     extensions.push({ key, value });
                 }
             }
-            const servers = (_v = (_u = operationObject.servers) !== null && _u !== void 0 ? _u : pathObject.servers) !== null && _v !== void 0 ? _v : openapiData.servers;
-            const security = (_w = operationObject.security) !== null && _w !== void 0 ? _w : openapiData.security;
+            const servers = (_w = (_v = operationObject.servers) !== null && _v !== void 0 ? _v : pathObject.servers) !== null && _w !== void 0 ? _w : openapiData.servers;
+            const security = (_x = operationObject.security) !== null && _x !== void 0 ? _x : openapiData.security;
             // Add security schemes so we know how to handle security.
-            const securitySchemes = (_x = openapiData.components) === null || _x === void 0 ? void 0 : _x.securitySchemes;
+            const securitySchemes = (_y = openapiData.components) === null || _y === void 0 ? void 0 : _y.securitySchemes;
             // Make sure schemes are lowercase. See: https://github.com/cloud-annotations/docusaurus-plugin-openapi/issues/79
             if (securitySchemes) {
                 for (let securityScheme of Object.values(securitySchemes)) {
@@ -245,7 +246,7 @@ function createItems(openapiData, options, sidebarOptions) {
                 }
             }
             let jsonRequestBodyExample;
-            const content = (_y = operationObject.requestBody) === null || _y === void 0 ? void 0 : _y.content;
+            const content = (_z = operationObject.requestBody) === null || _z === void 0 ? void 0 : _z.content;
             let body;
             for (let key in content) {
                 if (key.toLowerCase() === "application/json" ||
@@ -258,7 +259,7 @@ function createItems(openapiData, options, sidebarOptions) {
                 jsonRequestBodyExample = (0, createRequestExample_1.sampleRequestFromSchema)(body.schema);
             }
             // Handle vendor JSON media types
-            const bodyContent = (_z = operationObject.requestBody) === null || _z === void 0 ? void 0 : _z.content;
+            const bodyContent = (_0 = operationObject.requestBody) === null || _0 === void 0 ? void 0 : _0.content;
             if (bodyContent) {
                 const firstBodyContentKey = Object.keys(bodyContent)[0];
                 if (firstBodyContentKey.endsWith("+json")) {
@@ -325,13 +326,13 @@ function createItems(openapiData, options, sidebarOptions) {
         }
     }
     if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true ||
-        Object.entries((_1 = (_0 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _0 === void 0 ? void 0 : _0.schemas) !== null && _1 !== void 0 ? _1 : {})
+        Object.entries((_2 = (_1 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _1 === void 0 ? void 0 : _1.schemas) !== null && _2 !== void 0 ? _2 : {})
             .flatMap(([_, s]) => s["x-tags"])
             .filter((item) => !!item).length > 0) {
         // Gather schemas
-        for (let [schema, schemaObject] of Object.entries((_3 = (_2 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _2 === void 0 ? void 0 : _2.schemas) !== null && _3 !== void 0 ? _3 : {})) {
+        for (let [schema, schemaObject] of Object.entries((_4 = (_3 = openapiData === null || openapiData === void 0 ? void 0 : openapiData.components) === null || _3 === void 0 ? void 0 : _3.schemas) !== null && _4 !== void 0 ? _4 : {})) {
             if ((options === null || options === void 0 ? void 0 : options.showSchemas) === true || schemaObject["x-tags"]) {
-                const baseIdSpaces = (_5 = (_4 = schemaObject === null || schemaObject === void 0 ? void 0 : schemaObject.title) === null || _4 === void 0 ? void 0 : _4.replace(" ", "-").toLowerCase()) !== null && _5 !== void 0 ? _5 : "";
+                const baseIdSpaces = (_6 = (_5 = schemaObject === null || schemaObject === void 0 ? void 0 : schemaObject.title) === null || _5 === void 0 ? void 0 : _5.replace(" ", "-").toLowerCase()) !== null && _6 !== void 0 ? _6 : "";
                 const baseId = (0, kebabCase_1.default)(baseIdSpaces);
                 const schemaDescription = schemaObject.description;
                 let splitDescription;
@@ -355,6 +356,7 @@ function createItems(openapiData, options, sidebarOptions) {
                                 .replace(/((?:^|[^\\])(?:\\{2})*)"/g, "$1'")
                                 .replace(/\s+$/, "")
                             : "",
+                        sample: JSON.stringify((0, createResponseExample_1.sampleResponseFromSchema)(schemaObject)),
                     },
                     schema: schemaObject,
                 };
@@ -364,7 +366,7 @@ function createItems(openapiData, options, sidebarOptions) {
     }
     if ((sidebarOptions === null || sidebarOptions === void 0 ? void 0 : sidebarOptions.categoryLinkSource) === "tag") {
         // Get global tags
-        const tags = (_6 = openapiData.tags) !== null && _6 !== void 0 ? _6 : [];
+        const tags = (_7 = openapiData.tags) !== null && _7 !== void 0 ? _7 : [];
         // Get operation tags
         const apiItems = items.filter((item) => {
             return item.type === "api";

package/lib/openapi/types.d.ts

@@ -12,6 +12,7 @@ export interface OpenApiObject {
     tags?: TagObject[];
     externalDocs?: ExternalDocumentationObject;
     swagger?: string;
+    webhooks?: PathsObject;
     "x-webhooks"?: PathsObject;
     "x-tagGroups"?: TagGroupObject[];
 }
@@ -163,6 +164,7 @@ export interface ParameterObject {
     examples?: Map<ExampleObject>;
     content?: Map<MediaTypeObject>;
     param?: Object;
+    "x-enumDescriptions"?: Record<string, string>;
 }
 export interface ParameterObjectWithRef {
     name: string;
@@ -194,6 +196,7 @@ export interface MediaTypeObject {
     example?: any;
     examples?: Map<ExampleObject>;
     encoding?: Map<EncodingObject>;
+    type?: any;
 }
 export interface MediaTypeObjectWithRef {
     schema?: SchemaObjectWithRef | ReferenceObject;
@@ -279,6 +282,7 @@ export type SchemaObject = Omit<JSONSchema, "type" | "allOf" | "oneOf" | "anyOf"
     example?: any;
     deprecated?: boolean;
     "x-tags"?: string[];
+    "x-enumDescriptions"?: Record<string, string>;
 };
 export type SchemaObjectWithRef = Omit<JSONSchema, "type" | "allOf" | "oneOf" | "anyOf" | "not" | "items" | "properties" | "additionalProperties"> & {
     type?: "string" | "number" | "integer" | "boolean" | "object" | "array";

package/lib/openapi/utils/services/OpenAPIParser.js

@@ -215,7 +215,7 @@ class OpenAPIParser {
         })
             .filter((child) => child !== undefined);
         for (const { $ref: subSchemaRef, schema: subSchema } of allOfSchemas) {
-            const { type, enum: enumProperty, properties, items, required, oneOf, anyOf, title, ...otherConstraints } = subSchema;
+            const { type, enum: enumProperty, "x-enumDescription": enumDescription, properties, items, required, oneOf, anyOf, title, ...otherConstraints } = subSchema;
             if (receiver.type !== type &&
                 receiver.type !== undefined &&
                 type !== undefined) {

package/lib/options.js

@@ -8,17 +8,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OptionsSchema = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
+const sidebarGenerators = utils_validation_1.Joi.object({
+    createDocItem: utils_validation_1.Joi.function(),
+});
 const sidebarOptions = utils_validation_1.Joi.object({
     groupPathsBy: utils_validation_1.Joi.string().valid("tag", "tagGroup"),
     categoryLinkSource: utils_validation_1.Joi.string().valid("tag", "info", "auto"),
     customProps: utils_validation_1.Joi.object(),
     sidebarCollapsible: utils_validation_1.Joi.boolean(),
     sidebarCollapsed: utils_validation_1.Joi.boolean(),
+    sidebarGenerators: sidebarGenerators,
 });
 const markdownGenerators = utils_validation_1.Joi.object({
     createApiPageMD: utils_validation_1.Joi.function(),
     createInfoPageMD: utils_validation_1.Joi.function(),
     createTagPageMD: utils_validation_1.Joi.function(),
+    createSchemaPageMD: utils_validation_1.Joi.function(),
 });
 exports.OptionsSchema = utils_validation_1.Joi.object({
     id: utils_validation_1.Joi.string().required(),

package/lib/sidebars/index.js

@@ -23,11 +23,33 @@ function isInfoItem(item) {
 function isSchemaItem(item) {
     return item.type === "schema";
 }
+const createDocItem = (item, { sidebarOptions: { customProps }, basePath }) => {
+    var _a, _b;
+    const sidebar_label = item.frontMatter.sidebar_label;
+    const title = item.title;
+    const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
+    const className = item.type === "api"
+        ? (0, clsx_1.default)({
+            "menu__list-item--deprecated": item.api.deprecated,
+            "api-method": !!item.api.method,
+        }, item.api.method)
+        : (0, clsx_1.default)({
+            "menu__list-item--deprecated": item.schema.deprecated,
+        }, "schema");
+    return {
+        type: "doc",
+        id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+        label: (_b = (_a = sidebar_label) !== null && _a !== void 0 ? _a : title) !== null && _b !== void 0 ? _b : id,
+        customProps: customProps,
+        className: className ? className : undefined,
+    };
+};
 function groupByTags(items, sidebarOptions, options, tags, docPath) {
+    var _a, _b;
     let { outputDir, label, showSchemas } = options;
     // Remove trailing slash before proceeding
     outputDir = outputDir.replace(/\/$/, "");
-    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
+    const { sidebarCollapsed, sidebarCollapsible, categoryLinkSource } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
     const infoItems = items.filter(isInfoItem);
     const schemaItems = items.filter(isSchemaItem);
@@ -61,27 +83,11 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
     const basePath = docPath
         ? outputDir.split(docPath)[1].replace(/^\/+/g, "")
         : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
-    function createDocItem(item) {
-        var _a, _b;
-        const sidebar_label = item.frontMatter.sidebar_label;
-        const title = item.title;
-        const id = item.type === "schema" ? `schemas/${item.id}` : item.id;
-        const className = item.type === "api"
-            ? (0, clsx_1.default)({
-                "menu__list-item--deprecated": item.api.deprecated,
-                "api-method": !!item.api.method,
-            }, item.api.method)
-            : (0, clsx_1.default)({
-                "menu__list-item--deprecated": item.schema.deprecated,
-            }, "schema");
-        return {
-            type: "doc",
-            id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
-            label: (_b = (_a = sidebar_label) !== null && _a !== void 0 ? _a : title) !== null && _b !== void 0 ? _b : id,
-            customProps: customProps,
-            className: className ? className : undefined,
-        };
-    }
+    const createDocItemFnContext = {
+        sidebarOptions,
+        basePath,
+    };
+    const createDocItemFn = (_b = (_a = sidebarOptions.sidebarGenerators) === null || _a === void 0 ? void 0 : _a.createDocItem) !== null && _b !== void 0 ? _b : createDocItem;
     let rootIntroDoc = undefined;
     if (infoItems.length === 1) {
         const infoItem = infoItems[0];
@@ -139,14 +145,14 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
             link: linkConfig,
             collapsible: sidebarCollapsible,
             collapsed: sidebarCollapsed,
-            items: [...taggedSchemaItems, ...taggedApiItems].map(createDocItem),
+            items: [...taggedSchemaItems, ...taggedApiItems].map((item) => createDocItemFn(item, createDocItemFnContext)),
         };
     })
         .filter((item) => item.items.length > 0); // Filter out any categories with no items.
     // Handle items with no tag
     const untaggedItems = apiItems
         .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-        .map(createDocItem);
+        .map((item) => createDocItemFn(item, createDocItemFnContext));
     let untagged = [];
     if (untaggedItems.length > 0) {
         untagged = [
@@ -157,7 +163,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
                 collapsed: sidebarCollapsed,
                 items: apiItems
                     .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-                    .map(createDocItem),
+                    .map((item) => createDocItemFn(item, createDocItemFnContext)),
             },
         ];
     }
@@ -171,7 +177,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
                 collapsed: sidebarCollapsed,
                 items: schemaItems
                     .filter(({ schema }) => !schema["x-tags"])
-                    .map(createDocItem),
+                    .map((item) => createDocItemFn(item, createDocItemFnContext)),
             },
         ];
     }

package/lib/types.d.ts

@@ -1,3 +1,4 @@
+import { SidebarItemDoc } from "@docusaurus/plugin-content-docs/src/sidebars/types";
 import type Request from "postman-collection";
 import { InfoObject, OperationObject, SchemaObject, SecuritySchemeObject, TagObject } from "./openapi/types";
 export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
@@ -34,6 +35,13 @@ export interface MarkdownGenerator {
     createTagPageMD?: (pageData: TagPageMetadata) => string;
     createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
 }
+export type ApiDocItemGenerator = (item: ApiPageMetadata | SchemaPageMetadata, context: {
+    sidebarOptions: SidebarOptions;
+    basePath: string;
+}) => SidebarItemDoc;
+export interface SidebarGenerators {
+    createDocItem?: ApiDocItemGenerator;
+}
 export interface SidebarOptions {
     groupPathsBy?: string;
     categoryLinkSource?: "info" | "tag" | "auto";
@@ -42,6 +50,7 @@ export interface SidebarOptions {
     };
     sidebarCollapsible?: boolean;
     sidebarCollapsed?: boolean;
+    sidebarGenerators?: SidebarGenerators;
 }
 export interface APIVersionOptions {
     specPath: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "4.0.1",
+  "version": "4.2.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,7 +28,7 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/types": "^3.0.1",
+    "@docusaurus/types": "^3.5.0",
     "@types/fs-extra": "^9.0.13",
     "@types/json-pointer": "^1.0.31",
     "@types/json-schema": "^7.0.9",
@@ -38,15 +38,15 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.5.4",
-    "@docusaurus/plugin-content-docs": "^3.0.1",
-    "@docusaurus/utils": "^3.0.1",
-    "@docusaurus/utils-validation": "^3.0.1",
+    "@docusaurus/plugin-content-docs": "^3.5.0",
+    "@docusaurus/utils": "^3.5.0",
+    "@docusaurus/utils-validation": "^3.5.0",
     "@redocly/openapi-core": "^1.10.5",
+    "allof-merge": "^0.6.6",
     "chalk": "^4.1.2",
     "clsx": "^1.1.1",
     "fs-extra": "^9.0.1",
     "json-pointer": "^0.6.2",
-    "json-schema-merge-allof": "^0.8.1",
     "json5": "^2.2.3",
     "lodash": "^4.17.20",
     "mustache": "^4.2.0",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "e228de93d24062c46fb206548dca7af9bc6264bb"
+  "gitHead": "e7295a8aa6f3fab5ccc4f8f9ad0e6c33d785aa16"
 }

package/src/index.ts

@@ -278,7 +278,11 @@ title: "{{{title}}}"
 description: "{{{frontMatter.description}}}"
 sidebar_label: "{{{title}}}"
 hide_title: true
+{{#schema}}
+hide_table_of_contents: true
+{{/schema}}
 schema: true
+sample: {{{frontMatter.sample}}}
 custom_edit_url: null
 ---
 

package/src/markdown/__snapshots__/createSchema.test.ts.snap

@@ -364,6 +364,111 @@ Array [
   qualifierMessage={undefined}
   schema={{ type: \\"string\\" }}
 ></SchemaItem>;
+",
+  "<SchemaItem
+  collapsible={false}
+  name={\\"parentProp1\\"}
+  required={false}
+  schemaName={\\"string\\"}
+  qualifierMessage={undefined}
+  schema={{ type: \\"string\\" }}
+></SchemaItem>;
+",
+  "<SchemaItem
+  collapsible={false}
+  name={\\"parentProp2\\"}
+  required={false}
+  schemaName={\\"string\\"}
+  qualifierMessage={undefined}
+  schema={{ type: \\"string\\" }}
+></SchemaItem>;
+",
+]
+`;
+
+exports[`createNodes anyOf should render oneOf within anyOf 1`] = `
+Array [
+  "<SchemaItem collapsible={true} className={\\"schemaItem\\"}>
+  <details style={{}} className={\\"openapi-markdown__details\\"}>
+    <summary style={{}}>
+      <span className={\\"openapi-schema__container\\"}>
+        <strong className={\\"openapi-schema__property\\"}>oneOfProperty</strong>
+        <span className={\\"openapi-schema__name\\"}>object</span>
+      </span>
+    </summary>
+    <div style={{ marginLeft: \\"1rem\\" }}>
+      <div>
+        <span className={\\"badge badge--info\\"} style={{ marginBottom: \\"1rem\\" }}>
+          anyOf
+        </span>
+        <SchemaTabs>
+          <TabItem label={\\"An int or a bool\\"} value={\\"0-item-properties\\"}>
+            <div>
+              <span
+                className={\\"badge badge--info\\"}
+                style={{ marginBottom: \\"1rem\\" }}
+              >
+                oneOf
+              </span>
+              <SchemaTabs>
+                <TabItem label={\\"MOD1\\"} value={\\"0-item-properties\\"}>
+                  <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+                    integer
+                  </div>
+                </TabItem>
+                <TabItem label={\\"MOD2\\"} value={\\"1-item-properties\\"}>
+                  <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+                    boolean
+                  </div>
+                </TabItem>
+              </SchemaTabs>
+            </div>
+          </TabItem>
+          <TabItem label={\\"MOD2\\"} value={\\"1-item-properties\\"}>
+            <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+              string
+            </div>
+          </TabItem>
+        </SchemaTabs>
+      </div>
+    </div>
+  </details>
+</SchemaItem>;
+",
+]
+`;
+
+exports[`createNodes anyOf should render primitives within anyOf 1`] = `
+Array [
+  "<SchemaItem collapsible={true} className={\\"schemaItem\\"}>
+  <details style={{}} className={\\"openapi-markdown__details\\"}>
+    <summary style={{}}>
+      <span className={\\"openapi-schema__container\\"}>
+        <strong className={\\"openapi-schema__property\\"}>oneOfProperty</strong>
+        <span className={\\"openapi-schema__name\\"}>object</span>
+      </span>
+    </summary>
+    <div style={{ marginLeft: \\"1rem\\" }}>
+      <div>
+        <span className={\\"badge badge--info\\"} style={{ marginBottom: \\"1rem\\" }}>
+          anyOf
+        </span>
+        <SchemaTabs>
+          <TabItem label={\\"MOD1\\"} value={\\"0-item-properties\\"}>
+            <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+              integer
+            </div>
+          </TabItem>
+          <TabItem label={\\"MOD2\\"} value={\\"1-item-properties\\"}>
+            <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+              boolean
+            </div>
+          </TabItem>
+        </SchemaTabs>
+      </div>
+    </div>
+  </details>
+</SchemaItem>;
 ",
 ]
 `;
@@ -624,6 +729,15 @@ Array [
   qualifierMessage={undefined}
   schema={{ type: \\"string\\" }}
 ></SchemaItem>;
+",
+  "<SchemaItem
+  collapsible={false}
+  name={\\"type\\"}
+  required={false}
+  schemaName={\\"string\\"}
+  qualifierMessage={undefined}
+  schema={{ type: \\"string\\" }}
+></SchemaItem>;
 ",
 ]
 `;
@@ -710,6 +824,34 @@ Array [
   qualifierMessage={undefined}
   schema={{ type: \\"string\\" }}
 ></SchemaItem>;
+",
+  "<div className={\\"openapi-discriminator__item openapi-schema__list-item\\"}>
+  <div>
+    <span className={\\"openapi-schema__container\\"}>
+      <strong
+        className={\\"openapi-discriminator__name openapi-schema__property\\"}
+      >
+        type
+      </strong>
+      <span className={\\"openapi-schema__name\\"}>string</span>
+    </span>
+    <div style={{ paddingLeft: \\"1rem\\" }}>
+      **Possible values:** [\`typeA\`, \`typeB\`]
+    </div>
+    <DiscriminatorTabs className={\\"openapi-tabs__discriminator\\"}>
+      <TabItem label={\\"typeA\\"} value={\\"0-item-discriminator\\"}>
+        <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+          #/definitions/TypeA
+        </div>
+      </TabItem>
+      <TabItem label={\\"typeB\\"} value={\\"1-item-discriminator\\"}>
+        <div style={{ marginTop: \\".5rem\\", marginBottom: \\".5rem\\" }}>
+          #/definitions/TypeB
+        </div>
+      </TabItem>
+    </DiscriminatorTabs>
+  </div>
+</div>;
 ",
 ]
 `;

package/src/markdown/createCallbackMethodEndpoint.ts

@@ -0,0 +1,19 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import { create } from "./utils";
+
+export function createCallbackMethodEndpoint(method: String, path: String) {
+  return [
+    create("MethodEndpoint", {
+      method: method,
+      path: path,
+      context: "callback",
+    }),
+    "\n\n",
+  ];
+}

package/src/markdown/createCallbacks.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import { createCallbackMethodEndpoint } from "./createCallbackMethodEndpoint";
 import { createDescription } from "./createDescription";
-import { createMethodEndpoint } from "./createMethodEndpoint";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createStatusCodes } from "./createStatusCodes";
 import { create } from "./utils";
@@ -78,7 +78,7 @@ export function createCallbacks({ callbacks }: Props) {
                 label: `${method.toUpperCase()} ${name}`,
                 value: `${method}-${name}`,
                 children: [
-                  createMethodEndpoint(method, path),
+                  createCallbackMethodEndpoint(method, path),
                   // TODO: add `deprecation notice` when markdown support is added
                   createDescription(description),
                   createRequestBodyDetails({

package/src/markdown/createContactInfo.ts

@@ -33,7 +33,7 @@ export function createContactInfo(contact: ContactObject) {
       }),
       guard(url, () =>
         create("span", {
-          children: ["URL: ", `[${url}](mailto:${url})`],
+          children: ["URL: ", `[${url}](${url})`],
         })
       ),
     ],

package/src/markdown/createDeprecationNotice.ts

@@ -23,8 +23,9 @@ export function createDeprecationNotice({
   return guard(deprecated, () =>
     createAdmonition({
       children:
-        clean(description) ??
-        "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
+        description && description.length > 0
+          ? clean(description)
+          : "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
     })
   );
 }

package/src/markdown/createMethodEndpoint.ts

@@ -8,5 +8,12 @@
 import { create } from "./utils";
 
 export function createMethodEndpoint(method: String, path: String) {
-  return [create("MethodEndpoint", { method: method, path: path }), "\n\n"];
+  return [
+    create("MethodEndpoint", {
+      method: method,
+      path: path,
+      context: "endpoint",
+    }),
+    "\n\n",
+  ];
 }

package/src/markdown/createParamsDetails.ts

@@ -5,53 +5,18 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { createDetails } from "./createDetails";
-import { createDetailsSummary } from "./createDetailsSummary";
 import { create } from "./utils";
 import { ApiItem } from "../types";
 
 interface Props {
   parameters: ApiItem["parameters"];
-  type: "path" | "query" | "header" | "cookie";
 }
 
-export function createParamsDetails({ parameters, type }: Props) {
-  if (parameters === undefined) {
-    return undefined;
-  }
-  const params = parameters.filter((param) => param?.in === type);
-  if (params.length === 0) {
-    return undefined;
-  }
-
-  return createDetails({
-    className: "openapi-markdown__details",
-    "data-collapsed": false,
-    open: true,
-    style: { marginBottom: "1rem" },
-    children: [
-      createDetailsSummary({
-        children: [
-          create("h3", {
-            className: "openapi-markdown__details-summary-header-params",
-            children: `${
-              type.charAt(0).toUpperCase() + type.slice(1)
-            } Parameters`,
-          }),
-        ],
-      }),
-      create("div", {
-        children: [
-          create("ul", {
-            children: params.map((param) =>
-              create("ParamsItem", {
-                className: "paramsItem",
-                param: param,
-              })
-            ),
-          }),
-        ],
-      }),
-    ],
-  });
+export function createParamsDetails({ parameters }: Props) {
+  return [
+    create("ParamsDetails", {
+      parameters: parameters,
+    }),
+    "\n\n",
+  ];
 }