docusaurus-plugin-openapi-docs 0.0.0-beta.691 → 0.0.0-beta.719

package/src/markdown/createDeprecationNotice.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { guard, Props, render } from "./utils";
+import { clean, guard, Props, render } from "./utils";
 
 function createAdmonition({ children }: Props) {
   return `:::caution deprecated\n\n${render(children)}\n\n:::`;
@@ -23,7 +23,7 @@ export function createDeprecationNotice({
   return guard(deprecated, () =>
     createAdmonition({
       children:
-        description ??
+        clean(description) ??
         "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
     })
   );

package/src/markdown/createDescription.ts

@@ -5,16 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { greaterThan, codeFence, lessThan } from "./utils";
+import { clean } from "./utils";
 
 export function createDescription(description: string | undefined) {
-  if (!description) {
-    return "";
-  }
-  return `\n\n${description
-    .replace(lessThan, "<")
-    .replace(greaterThan, ">")
-    .replace(codeFence, function (match) {
-      return match.replace(/\\>/g, ">");
-    })}\n\n`;
+  return `\n\n${clean(description)}\n\n`;
 }

package/src/markdown/createHeading.ts

@@ -5,16 +5,19 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { create, greaterThan, lessThan } from "./utils";
+import { clean, create } from "./utils";
 
 export function createHeading(heading: string) {
   return [
-    create("h1", {
-      className: "openapi__heading",
-      children: `${heading
-        .replace(lessThan, "<")
-        .replace(greaterThan, ">")}`,
-    }),
+    create(
+      "Heading",
+      {
+        children: clean(heading),
+        as: "h1",
+        className: "openapi__heading",
+      },
+      { inline: true }
+    ),
     `\n\n`,
   ];
 }

package/src/markdown/createLicense.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { LicenseObject } from "../openapi/types";
 import { create, guard } from "./utils";
+import { LicenseObject } from "../openapi/types";
 
 export function createLicense(license: LicenseObject) {
   if (!license || !Object.keys(license).length) return "";

package/src/markdown/createLogo.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { LogoObject } from "../openapi/types";
 import { create, guard } from "./utils";
+import { LogoObject } from "../openapi/types";
 
 export function createLogo(
   logo: LogoObject | undefined,

package/src/markdown/createParamsDetails.ts

@@ -5,10 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { ApiItem } from "../types";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 import { create } from "./utils";
+import { ApiItem } from "../types";
 
 interface Props {
   parameters: ApiItem["parameters"];

package/src/markdown/createRequestBodyDetails.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { MediaTypeObject } from "../openapi/types";
 import { createRequestSchema } from "./createRequestSchema";
+import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
   title: string;
@@ -19,6 +19,6 @@ interface Props {
   };
 }
 
-export function createRequestBodyDetails({ title, body }: Props): any {
+export function createRequestBodyDetails({ title, body }: Props) {
   return createRequestSchema({ title, body });
 }

package/src/markdown/createRequestHeader.ts

@@ -5,6 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import { create } from "./utils";
+
 export function createRequestHeader(header: string) {
-  return `## ${header}\n\n`;
+  return [
+    create(
+      "Heading",
+      {
+        children: header,
+        id: header.replace(" ", "-").toLowerCase(),
+        as: "h2",
+        className: "openapi-tabs__heading",
+      },
+      { inline: true }
+    ),
+    `\n\n`,
+  ];
 }

package/src/markdown/createRequestSchema.ts

@@ -5,12 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { MediaTypeObject } from "../openapi/types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 import { createNodes } from "./createSchema";
 import { create, guard } from "./utils";
+import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
   style?: any;

package/src/markdown/createResponseSchema.ts

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { MediaTypeObject } from "../openapi/types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
@@ -16,6 +15,7 @@ import {
   createResponseExamples,
 } from "./createStatusCodes";
 import { create, guard } from "./utils";
+import { MediaTypeObject } from "../openapi/types";
 
 interface Props {
   style?: any;

package/src/markdown/createSchema.test.ts

@@ -7,11 +7,11 @@
 
 import * as prettier from "prettier";
 
-import { SchemaObject } from "../openapi/types";
 import { createNodes } from "./createSchema";
+import { SchemaObject } from "../openapi/types";
 
 describe("createNodes", () => {
-  it("should create readable MODs for oneOf primitive properties", () => {
+  it("should create readable MODs for oneOf primitive properties", async () => {
     const schema: SchemaObject = {
       type: "object",
       properties: {
@@ -48,8 +48,10 @@ describe("createNodes", () => {
       },
     };
     expect(
-      createNodes(schema, "request").map((md: any) =>
-        prettier.format(md, { parser: "babel" })
+      await Promise.all(
+        createNodes(schema, "request").map(
+          async (md: any) => await prettier.format(md, { parser: "babel" })
+        )
       )
     ).toMatchSnapshot();
   });

package/src/markdown/createSchema.ts

@@ -7,7 +7,6 @@
 
 import clsx from "clsx";
 
-import { SchemaObject } from "../openapi/types";
 import {
   createClosingArrayBracket,
   createOpeningArrayBracket,
@@ -17,6 +16,7 @@ import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 import { getQualifierMessage, getSchemaName } from "./schema";
 import { create, guard } from "./utils";
+import { SchemaObject } from "../openapi/types";
 
 const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
 
@@ -44,7 +44,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
     ignoreAdditionalProperties: true,
   });
 
-  const required = allOf.reduce((acc, cur) => {
+  const mergedRequired = allOf.reduce((acc, cur) => {
     if (Array.isArray(cur.required)) {
       const next = [...acc, ...cur.required];
       return next;
@@ -52,7 +52,7 @@ export function mergeAllOf(allOf: SchemaObject[]) {
     return acc;
   }, [] as any);
 
-  return { mergedSchemas, required };
+  return { mergedSchemas, mergedRequired };
 }
 
 /**
@@ -260,9 +260,8 @@ function createItems(schema: SchemaObject) {
     // TODO: figure out if and how we should pass merged required array
     const {
       mergedSchemas,
-    }: { mergedSchemas: SchemaObject; required: string[] } = mergeAllOf(
-      schema.items?.allOf
-    );
+    }: { mergedSchemas: SchemaObject; mergedRequired: string[] | boolean } =
+      mergeAllOf(schema.items?.allOf);
 
     // Handles combo anyOf/oneOf + properties
     if (
@@ -596,7 +595,6 @@ function createEdges({
   discriminator,
 }: EdgeProps): any {
   const schemaName = getSchemaName(schema);
-
   if (discriminator !== undefined && discriminator.propertyName === name) {
     return createPropertyDiscriminator(
       name,
@@ -618,13 +616,10 @@ function createEdges({
   }
 
   if (schema.allOf !== undefined) {
-    const {
-      mergedSchemas,
-      required,
-    }: { mergedSchemas: SchemaObject; required: string[] | boolean } =
-      mergeAllOf(schema.allOf);
+    const { mergedSchemas }: { mergedSchemas: SchemaObject } = mergeAllOf(
+      schema.allOf
+    );
     const mergedSchemaName = getSchemaName(mergedSchemas);
-
     if (
       mergedSchemas.oneOf !== undefined ||
       mergedSchemas.anyOf !== undefined
@@ -685,8 +680,8 @@ function createEdges({
       collapsible: false,
       name,
       required: Array.isArray(required) ? required.includes(name) : required,
-      schemaName: schemaName,
-      qualifierMessage: getQualifierMessage(schema),
+      schemaName: mergedSchemaName,
+      qualifierMessage: getQualifierMessage(mergedSchemas),
       schema: mergedSchemas,
     });
   }
@@ -817,9 +812,18 @@ export function createNodes(
       style: {
         marginTop: ".5rem",
         marginBottom: ".5rem",
-        marginLeft: "1rem",
       },
-      children: createDescription(schema.type),
+      children: [
+        createDescription(schema.type),
+        guard(getQualifierMessage(schema), (message) =>
+          create("div", {
+            style: {
+              paddingTop: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+      ],
     });
   }
 
@@ -829,9 +833,18 @@ export function createNodes(
       style: {
         marginTop: ".5rem",
         marginBottom: ".5rem",
-        marginLeft: "1rem",
       },
-      children: [createDescription(schema)],
+      children: [
+        createDescription(schema),
+        guard(getQualifierMessage(schema), (message) =>
+          create("div", {
+            style: {
+              paddingTop: "1rem",
+            },
+            children: createDescription(message),
+          })
+        ),
+      ],
     });
   }
 

package/src/markdown/createStatusCodes.ts

@@ -7,14 +7,14 @@
 
 import format from "xml-formatter";
 
-import { sampleResponseFromSchema } from "../openapi/createResponseExample";
-import { ApiItem } from "../types";
 import { createDescription } from "./createDescription";
 import { createDetails } from "./createDetails";
 import { createDetailsSummary } from "./createDetailsSummary";
 import { createResponseSchema } from "./createResponseSchema";
 import { create } from "./utils";
 import { guard } from "./utils";
+import { sampleResponseFromSchema } from "../openapi/createResponseExample";
+import { ApiItem } from "../types";
 
 export default function json2xml(o: any, tab: any) {
   var toXml = function (v: any, name: string, ind: any) {
@@ -54,6 +54,8 @@ export default function json2xml(o: any, tab: any) {
 }
 
 interface Props {
+  id?: string;
+  label?: string;
   responses: ApiItem["responses"];
 }
 
@@ -125,7 +127,7 @@ export function createResponseExamples(
           value: `${exampleName}`,
           children: [
             guard(exampleValue.summary, (summary) => [
-              create("p", {
+              create("Markdown", {
                 children: ` ${summary}`,
               }),
             ]),
@@ -141,7 +143,7 @@ export function createResponseExamples(
         value: `${exampleName}`,
         children: [
           guard(exampleValue.summary, (summary) => [
-            create("p", {
+            create("Markdown", {
               children: ` ${summary}`,
             }),
           ]),
@@ -169,7 +171,7 @@ export function createResponseExample(responseExample: any, mimeType: string) {
       value: `Example`,
       children: [
         guard(responseExample.summary, (summary) => [
-          create("p", {
+          create("Markdown", {
             children: ` ${summary}`,
           }),
         ]),
@@ -185,7 +187,7 @@ export function createResponseExample(responseExample: any, mimeType: string) {
     value: `Example`,
     children: [
       guard(responseExample.summary, (summary) => [
-        create("p", {
+        create("Markdown", {
           children: ` ${summary}`,
         }),
       ]),
@@ -254,7 +256,7 @@ export function createExampleFromSchema(schema: any, mimeType: string) {
   return undefined;
 }
 
-export function createStatusCodes({ responses }: Props) {
+export function createStatusCodes({ label, id, responses }: Props) {
   if (responses === undefined) {
     return undefined;
   }
@@ -269,6 +271,8 @@ export function createStatusCodes({ responses }: Props) {
       create("div", {
         children: [
           create("ApiTabs", {
+            label,
+            id,
             children: codes.map((code) => {
               const responseHeaders: any = responses[code].headers;
               return create("TabItem", {

package/src/markdown/createVersionBadge.ts

@@ -9,10 +9,14 @@ import { create, guard } from "./utils";
 
 export function createVersionBadge(version: string | undefined) {
   return guard(version, (version) => [
-    create("span", {
-      className: "theme-doc-version-badge badge badge--secondary",
-      children: `Version: ${escape(version)}`,
-    }),
+    create(
+      "span",
+      {
+        className: "theme-doc-version-badge badge badge--secondary",
+        children: `Version: ${escape(version)}`,
+      },
+      { inline: true }
+    ),
     `\n\n`,
   ]);
 }

package/src/markdown/index.ts

@@ -5,15 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import {
-  ContactObject,
-  LicenseObject,
-  MediaTypeObject,
-  SecuritySchemeObject,
-} from "../openapi/types";
-import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
 import { createAuthentication } from "./createAuthentication";
 import { createAuthorization } from "./createAuthorization";
+import { createCallbacks } from "./createCallbacks";
 import { createContactInfo } from "./createContactInfo";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
@@ -25,13 +19,26 @@ import { createMethodEndpoint } from "./createMethodEndpoint";
 import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createRequestHeader } from "./createRequestHeader";
+import { createNodes } from "./createSchema";
 import { createStatusCodes } from "./createStatusCodes";
 import { createTermsOfService } from "./createTermsOfService";
 import { createVendorExtensions } from "./createVendorExtensions";
 import { createVersionBadge } from "./createVersionBadge";
-import { greaterThan, lessThan, render } from "./utils";
+import { create, greaterThan, lessThan, render } from "./utils";
+import {
+  ContactObject,
+  LicenseObject,
+  MediaTypeObject,
+  SecuritySchemeObject,
+} from "../openapi/types";
+import {
+  ApiPageMetadata,
+  InfoPageMetadata,
+  SchemaPageMetadata,
+  TagPageMetadata,
+} from "../types";
 
-interface Props {
+interface RequestBodyProps {
   title: string;
   body: {
     content?: {
@@ -54,6 +61,7 @@ export function createApiPageMD({
     parameters,
     requestBody,
     responses,
+    callbacks,
   },
   infoPath,
   frontMatter,
@@ -68,14 +76,19 @@ export function createApiPageMD({
     `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.replace(lessThan, "<").replace(greaterThan, ">")),
+    createHeading(title),
     createMethodEndpoint(method, path),
     infoPath && createAuthorization(infoPath),
-    frontMatter.show_extensions && createVendorExtensions(extensions),
+    frontMatter.show_extensions
+      ? createVendorExtensions(extensions)
+      : undefined,
     createDeprecationNotice({ deprecated, description: deprecatedDescription }),
     createDescription(description),
-    createRequestHeader("Request"),
+    requestBody || parameters ? createRequestHeader("Request") : undefined,
     createParamsDetails({ parameters, type: "path" }),
     createParamsDetails({ parameters, type: "query" }),
     createParamsDetails({ parameters, type: "header" }),
@@ -83,8 +96,9 @@ export function createApiPageMD({
     createRequestBodyDetails({
       title: "Body",
       body: requestBody,
-    } as Props),
+    } as RequestBodyProps),
     createStatusCodes({ responses }),
+    createCallbacks({ callbacks }),
   ]);
 }
 
@@ -104,13 +118,14 @@ export function createInfoPageMD({
 }: InfoPageMetadata) {
   return render([
     `import ApiLogo from "@theme/ApiLogo";\n`,
+    `import Heading from "@theme/Heading";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
     `import TabItem from "@theme/TabItem";\n`,
     `import Export from "@theme/ApiExplorer/Export";\n\n`,
 
     createVersionBadge(version),
     createDownload(downloadUrl),
-    createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
+    createHeading(title),
     createLogo(logo, darkLogo),
     createDescription(description),
     createAuthentication(securitySchemes as unknown as SecuritySchemeObject),
@@ -123,3 +138,19 @@ export function createInfoPageMD({
 export function createTagPageMD({ tag: { description } }: TagPageMetadata) {
   return render([createDescription(description)]);
 }
+
+export function createSchemaPageMD({ schema }: SchemaPageMetadata) {
+  const { title = "", description } = schema;
+  return render([
+    `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
+    `import SchemaItem from "@theme/SchemaItem";\n`,
+    `import SchemaTabs from "@theme/SchemaTabs";\n`,
+    `import Heading from "@theme/Heading";\n`,
+    `import TabItem from "@theme/TabItem";\n\n`,
+    createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
+    createDescription(description),
+    create("ul", {
+      children: createNodes(schema, "response"),
+    }),
+  ]);
+}

package/src/markdown/schema.ts

@@ -40,6 +40,10 @@ function prettyName(schema: SchemaObject, circular?: boolean) {
     // return schema.type;
   }
 
+  if (schema.title && schema.type) {
+    return `${schema.title} (${schema.type})`;
+  }
+
   return schema.title ?? schema.type;
 }
 

package/src/markdown/utils.ts

@@ -9,16 +9,27 @@ export type Children = string | undefined | (string | string[] | undefined)[];
 
 export type Props = Record<string, any> & { children?: Children };
 
-export function create(tag: string, props: Props): string {
+export type Options = { inline?: boolean };
+
+export function create(
+  tag: string,
+  props: Props,
+  options: Options = {}
+): string {
   const { children, ...rest } = props;
 
   let propString = "";
   for (const [key, value] of Object.entries(rest)) {
     propString += `\n  ${key}={${JSON.stringify(value)}}`;
   }
-  propString += propString ? "\n" : "";
-
   let indentedChildren = render(children).replace(/^/gm, "  ");
+
+  if (options.inline) {
+    propString += `\n  children={${JSON.stringify(children)}}`;
+    indentedChildren = "";
+  }
+
+  propString += propString ? "\n" : "";
   indentedChildren += indentedChildren ? "\n" : "";
   return `<${tag}${propString}>\n${indentedChildren}</${tag}>`;
 }
@@ -27,7 +38,7 @@ export function guard<T>(
   value: T | undefined,
   cb: (value: T) => Children
 ): string {
-  if (!!value) {
+  if (!!value || value === 0) {
     const children = cb(value);
     return render(children);
   }
@@ -50,3 +61,25 @@ export const lessThan =
 export const greaterThan =
   /(?<!(button|code|details|summary|hr|br|span|strong|small|table|thead|tbody|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|bold|a|li|ol|ul|img|svg|div|center|\/|\s|"|'))>/gu;
 export const codeFence = /`{1,3}[\s\S]*?`{1,3}/g;
+export const curlyBrackets = /([{|}])/g;
+export const codeBlock = /(^```.*[\s\S]*?```$|`[^`].+?`)/gm;
+
+export function clean(value: string | undefined): string {
+  if (!value) {
+    return "";
+  }
+
+  let sections = value.split(codeBlock);
+  for (let sectionIndex in sections) {
+    if (!sections[sectionIndex].startsWith("`")) {
+      sections[sectionIndex] = sections[sectionIndex]
+        .replace(lessThan, "&lt;")
+        .replace(greaterThan, "&gt;")
+        .replace(codeFence, function (match) {
+          return match.replace(/\\>/g, ">");
+        })
+        .replace(curlyBrackets, "\\$1");
+    }
+  }
+  return sections.join("");
+}

package/src/openapi/__fixtures__/examples/openapi.yaml

@@ -11,3 +11,32 @@ paths:
       responses:
         200:
           description: OK
+
+tags:
+  - name: tag1
+    description: Everything about your Pets
+    x-displayName: Tag 1
+  - name: tag2
+    description: Tag 2 description
+    x-displayName: Tag 2
+  - name: tag3
+    description: Tag 3 description
+    x-displayName: Tag 3
+  - name: tag4
+    description: Tag 4 description
+    x-displayName: Tag 4
+
+x-tagGroups:
+  - name: Tag 1 & 2
+    tags:
+      - tag1
+      - tag2
+  - name: Trinity
+    tags:
+      - tag1
+      - tag2
+      - tag3
+  - name: Last Two
+    tags:
+      - tag3
+      - tag4

package/src/openapi/createRequestExample.ts

@@ -8,8 +8,8 @@
 import chalk from "chalk";
 import merge from "lodash/merge";
 
-import { mergeAllOf } from "../markdown/createSchema";
 import { SchemaObject } from "./types";
+import { mergeAllOf } from "../markdown/createSchema";
 
 interface OASTypeToTypeMap {
   string: string;

package/src/openapi/createResponseExample.ts

@@ -8,8 +8,8 @@
 import chalk from "chalk";
 import merge from "lodash/merge";
 
-import { mergeAllOf } from "../markdown/createSchema";
 import { SchemaObject } from "./types";
+import { mergeAllOf } from "../markdown/createSchema";
 
 interface OASTypeToTypeMap {
   string: string;