docusaurus-plugin-openapi-docs 0.0.0-348 → 0.0.0-351

package/src/markdown/index.ts

@@ -7,12 +7,16 @@
 
 import { escape } from "lodash";
 
+import { ContactObject, LicenseObject } from "../openapi/types";
 import { ApiPageMetadata, InfoPageMetadata } from "../types";
+import { createContactInfo } from "./createContactInfo";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
+import { createLicense } from "./createLicense";
 import { createParamsDetails } from "./createParamsDetails";
 import { createRequestBodyDetails } from "./createRequestBodyDetails";
 import { createStatusCodes } from "./createStatusCodes";
+import { createTermsOfService } from "./createTermsOfService";
 import { createVersionBadge } from "./createVersionBadge";
 import { render } from "./utils";
 
@@ -45,11 +49,14 @@ export function createApiPageMD({
 }
 
 export function createInfoPageMD({
-  info: { title, version, description },
+  info: { title, version, description, contact, license, termsOfService },
 }: InfoPageMetadata) {
   return render([
     createVersionBadge(version),
     `# ${escape(title)}\n\n`,
     createDescription(description),
+    createContactInfo(contact as ContactObject),
+    createTermsOfService(termsOfService),
+    createLicense(license as LicenseObject),
   ]);
 }

package/src/openapi/types.ts

@@ -400,6 +400,8 @@ export interface HttpSecuritySchemeObject {
   description?: string;
   scheme: string;
   bearerFormat?: string;
+  name?: string;
+  in?: string;
 }
 
 export interface Oauth2SecuritySchemeObject {

package/src/markdown/createParamsTable.ts

@@ -1,102 +0,0 @@
-/* ============================================================================
- * 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 { escape } from "lodash";
-
-import { ApiItem } from "../types";
-import { createDescription } from "./createDescription";
-import { createFullWidthTable } from "./createFullWidthTable";
-import { getQualifierMessage, getSchemaName } from "./schema";
-import { create, guard } from "./utils";
-
-interface Props {
-  parameters: ApiItem["parameters"];
-  type: "path" | "query" | "header" | "cookie";
-}
-
-export function createParamsTable({ parameters, type }: Props) {
-  if (parameters === undefined) {
-    return undefined;
-  }
-  const params = parameters.filter((param) => param?.in === type);
-  if (params.length === 0) {
-    return undefined;
-  }
-
-  return createFullWidthTable({
-    children: [
-      create("thead", {
-        children: create("tr", {
-          children: create("th", {
-            style: { textAlign: "left" },
-            children: `${
-              type.charAt(0).toUpperCase() + type.slice(1)
-            } Parameters`,
-          }),
-        }),
-      }),
-      create("tbody", {
-        children: params.map((param) =>
-          create("tr", {
-            children: create("td", {
-              children: [
-                create("code", { children: param.name }),
-                guard(param.schema, (schema) =>
-                  create("span", {
-                    style: { opacity: "0.6" },
-                    children: ` ${getSchemaName(schema)}`,
-                  })
-                ),
-                guard(param.required, () => [
-                  create("span", {
-                    style: { opacity: "0.6" },
-                    children: " — ",
-                  }),
-                  create("strong", {
-                    style: {
-                      fontSize: "var(--ifm-code-font-size)",
-                      color: "var(--openapi-required)",
-                    },
-                    children: " REQUIRED",
-                  }),
-                ]),
-                guard(getQualifierMessage(param.schema), (message) =>
-                  create("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: createDescription(message),
-                  })
-                ),
-                guard(param.description, (description) =>
-                  create("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: createDescription(description),
-                  })
-                ),
-                guard(param.example, (example) =>
-                  create("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: escape(`Example: ${example}`),
-                  })
-                ),
-                guard(param.examples, (examples) =>
-                  create("div", {
-                    style: { marginTop: "var(--ifm-table-cell-padding)" },
-                    children: Object.entries(examples).map(([k, v]) =>
-                      create("div", {
-                        children: escape(`Example (${k}): ${v.value}`),
-                      })
-                    ),
-                  })
-                ),
-              ],
-            }),
-          })
-        ),
-      }),
-    ],
-  });
-}

package/src/markdown/createSchemaTable.ts

@@ -1,275 +0,0 @@
-/* ============================================================================
- * 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 { MediaTypeObject, SchemaObject } from "../openapi/types";
-import { createDescription } from "./createDescription";
-import { createFullWidthTable } from "./createFullWidthTable";
-import { getQualifierMessage, getSchemaName } from "./schema";
-import { create, guard } from "./utils";
-
-function resolveAllOf(allOf: SchemaObject[]) {
-  // TODO: naive implementation (only supports objects, no directly nested allOf)
-  const properties = allOf.reduce((acc, cur) => {
-    if (cur.properties !== undefined) {
-      const next = { ...acc, ...cur.properties };
-      return next;
-    }
-    return acc;
-  }, {});
-
-  const required = allOf.reduce((acc, cur) => {
-    if (Array.isArray(cur.required)) {
-      const next = [...acc, ...cur.required];
-      return next;
-    }
-    return acc;
-  }, [] as string[]);
-
-  return { properties, required };
-}
-
-interface RowProps {
-  name: string;
-  schema: SchemaObject;
-  required: boolean;
-}
-
-function createRow({ name, schema, required }: RowProps) {
-  return create("tr", {
-    children: create("td", {
-      children: [
-        create("code", { children: name }),
-        create("span", {
-          style: { opacity: "0.6" },
-          children: ` ${getSchemaName(schema, true)}`,
-        }),
-        guard(required, () => [
-          create("span", {
-            style: { opacity: "0.6" },
-            children: " — ",
-          }),
-          create("strong", {
-            style: {
-              fontSize: "var(--ifm-code-font-size)",
-              color: "var(--openapi-required)",
-            },
-            children: " REQUIRED",
-          }),
-        ]),
-        guard(getQualifierMessage(schema), (message) =>
-          create("div", {
-            style: { marginTop: "var(--ifm-table-cell-padding)" },
-            children: createDescription(message),
-          })
-        ),
-        guard(schema.description, (description) =>
-          create("div", {
-            style: { marginTop: "var(--ifm-table-cell-padding)" },
-            children: createDescription(description),
-          })
-        ),
-        createRows({ schema: schema }),
-      ],
-    }),
-  });
-}
-
-interface RowsProps {
-  schema: SchemaObject;
-}
-
-function createRows({ schema }: RowsProps): string | undefined {
-  // object
-  if (schema.properties !== undefined) {
-    return createFullWidthTable({
-      style: {
-        marginTop: "var(--ifm-table-cell-padding)",
-        marginBottom: "0px",
-      },
-      children: create("tbody", {
-        children: Object.entries(schema.properties).map(([key, val]) =>
-          createRow({
-            name: key,
-            schema: val,
-            required: Array.isArray(schema.required)
-              ? schema.required.includes(key)
-              : false,
-          })
-        ),
-      }),
-    });
-  }
-
-  // TODO: This can be a bit complicated types can be missmatched and there can be nested allOfs which need to be resolved before merging properties
-  if (schema.allOf !== undefined) {
-    const { properties, required } = resolveAllOf(schema.allOf);
-    return createFullWidthTable({
-      style: {
-        marginTop: "var(--ifm-table-cell-padding)",
-        marginBottom: "0px",
-      },
-      children: create("tbody", {
-        children: Object.entries(properties).map(([key, val]) =>
-          createRow({
-            name: key,
-            schema: val,
-            required: Array.isArray(required) ? required.includes(key) : false,
-          })
-        ),
-      }),
-    });
-  }
-
-  // array
-  if (schema.items !== undefined) {
-    return createRows({ schema: schema.items });
-  }
-
-  // primitive
-  return undefined;
-}
-
-interface RowsRootProps {
-  schema: SchemaObject;
-}
-
-function createRowsRoot({ schema }: RowsRootProps) {
-  // object
-  if (schema.properties !== undefined) {
-    return Object.entries(schema.properties).map(([key, val]) =>
-      createRow({
-        name: key,
-        schema: val,
-        required: Array.isArray(schema.required)
-          ? schema.required.includes(key)
-          : false,
-      })
-    );
-  }
-
-  // TODO: This can be a bit complicated types can be missmatched and there can be nested allOfs which need to be resolved before merging properties
-  if (schema.allOf !== undefined) {
-    const { properties, required } = resolveAllOf(schema.allOf);
-    return Object.entries(properties).map(([key, val]) =>
-      createRow({
-        name: key,
-        schema: val,
-        required: Array.isArray(required) ? required.includes(key) : false,
-      })
-    );
-  }
-
-  // array
-  if (schema.items !== undefined) {
-    return create("tr", {
-      children: create("td", {
-        children: [
-          create("span", {
-            style: { opacity: "0.6" },
-            children: ` ${getSchemaName(schema, true)}`,
-          }),
-          createRows({ schema: schema.items }),
-        ],
-      }),
-    });
-  }
-
-  // primitive
-  return create("tr", {
-    children: create("td", {
-      children: [
-        create("span", {
-          style: { opacity: "0.6" },
-          children: ` ${schema.type}`,
-        }),
-        guard(getQualifierMessage(schema), (message) =>
-          create("div", {
-            style: { marginTop: "var(--ifm-table-cell-padding)" },
-            children: createDescription(message),
-          })
-        ),
-        guard(schema.description, (description) =>
-          create("div", {
-            style: { marginTop: "var(--ifm-table-cell-padding)" },
-            children: createDescription(description),
-          })
-        ),
-      ],
-    }),
-  });
-}
-
-interface Props {
-  style?: any;
-  title: string;
-  body: {
-    content?: {
-      [key: string]: MediaTypeObject;
-    };
-    description?: string;
-    required?: boolean;
-  };
-}
-
-export function createSchemaTable({ title, body, ...rest }: Props) {
-  if (body === undefined || body.content === undefined) {
-    return undefined;
-  }
-
-  // TODO:
-  // NOTE: We just pick a random content-type.
-  // How common is it to have multiple?
-  const randomFirstKey = Object.keys(body.content)[0];
-
-  const firstBody = body.content[randomFirstKey].schema;
-
-  if (firstBody === undefined) {
-    return undefined;
-  }
-
-  // we don't show the table if there is no properties to show
-  if (firstBody.properties !== undefined) {
-    if (Object.keys(firstBody.properties).length === 0) {
-      return undefined;
-    }
-  }
-
-  return createFullWidthTable({
-    ...rest,
-    children: [
-      create("thead", {
-        children: create("tr", {
-          children: create("th", {
-            style: { textAlign: "left" },
-            children: [
-              `${title} `,
-              guard(body.required, () => [
-                create("span", {
-                  style: { opacity: "0.6" },
-                  children: " — ",
-                }),
-                create("strong", {
-                  style: {
-                    fontSize: "var(--ifm-code-font-size)",
-                    color: "var(--openapi-required)",
-                  },
-                  children: " REQUIRED",
-                }),
-              ]),
-              create("div", {
-                children: createDescription(body.description),
-              }),
-            ],
-          }),
-        }),
-      }),
-      create("tbody", {
-        children: createRowsRoot({ schema: firstBody }),
-      }),
-    ],
-  });
-}