docusaurus-plugin-openapi-docs 0.0.0-361 → 0.0.0-366

package/lib/openapi/utils/types.d.ts

@@ -0,0 +1,306 @@
+declare type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+export interface OpenAPISpec {
+    openapi: string;
+    info: OpenAPIInfo;
+    servers?: OpenAPIServer[];
+    paths: OpenAPIPaths;
+    components?: OpenAPIComponents;
+    security?: OpenAPISecurityRequirement[];
+    tags?: OpenAPITag[];
+    externalDocs?: OpenAPIExternalDocumentation;
+    "x-webhooks"?: OpenAPIPaths;
+    webhooks?: OpenAPIPaths;
+}
+export interface OpenAPIInfo {
+    title: string;
+    version: string;
+    description?: string;
+    summary?: string;
+    termsOfService?: string;
+    contact?: OpenAPIContact;
+    license?: OpenAPILicense;
+}
+export interface OpenAPIServer {
+    url: string;
+    description?: string;
+    variables?: {
+        [name: string]: OpenAPIServerVariable;
+    };
+}
+export interface OpenAPIServerVariable {
+    enum?: string[];
+    default: string;
+    description?: string;
+}
+export interface OpenAPIPaths {
+    [path: string]: OpenAPIPath;
+}
+export interface OpenAPIRef {
+    $ref: string;
+}
+export declare type Referenced<T> = OpenAPIRef | T;
+export interface OpenAPIPath {
+    summary?: string;
+    description?: string;
+    get?: OpenAPIOperation;
+    put?: OpenAPIOperation;
+    post?: OpenAPIOperation;
+    delete?: OpenAPIOperation;
+    options?: OpenAPIOperation;
+    head?: OpenAPIOperation;
+    patch?: OpenAPIOperation;
+    trace?: OpenAPIOperation;
+    servers?: OpenAPIServer[];
+    parameters?: Array<Referenced<OpenAPIParameter>>;
+    $ref?: string;
+}
+export interface OpenAPIXCodeSample {
+    lang: string;
+    label?: string;
+    source: string;
+}
+export interface OpenAPIOperation {
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    externalDocs?: OpenAPIExternalDocumentation;
+    operationId?: string;
+    parameters?: Array<Referenced<OpenAPIParameter>>;
+    requestBody?: Referenced<OpenAPIRequestBody>;
+    responses: OpenAPIResponses;
+    callbacks?: {
+        [name: string]: Referenced<OpenAPICallback>;
+    };
+    deprecated?: boolean;
+    security?: OpenAPISecurityRequirement[];
+    servers?: OpenAPIServer[];
+    "x-codeSamples"?: OpenAPIXCodeSample[];
+    "x-code-samples"?: OpenAPIXCodeSample[];
+}
+export interface OpenAPIParameter {
+    name: string;
+    in?: OpenAPIParameterLocation;
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    allowEmptyValue?: boolean;
+    style?: OpenAPIParameterStyle;
+    explode?: boolean;
+    allowReserved?: boolean;
+    schema?: Referenced<OpenAPISchema>;
+    example?: any;
+    examples?: {
+        [media: string]: Referenced<OpenAPIExample>;
+    };
+    content?: {
+        [media: string]: OpenAPIMediaType;
+    };
+    encoding?: Record<string, OpenAPIEncoding>;
+    const?: any;
+}
+export interface OpenAPIExample {
+    value: any;
+    summary?: string;
+    description?: string;
+    externalValue?: string;
+}
+export interface OpenAPISchema {
+    $ref?: string;
+    type?: string | string[];
+    properties?: {
+        [name: string]: OpenAPISchema;
+    };
+    patternProperties?: {
+        [name: string]: OpenAPISchema;
+    };
+    additionalProperties?: boolean | OpenAPISchema;
+    unevaluatedProperties?: boolean | OpenAPISchema;
+    description?: string;
+    default?: any;
+    items?: OpenAPISchema | OpenAPISchema[] | boolean;
+    required?: string[];
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    deprecated?: boolean;
+    format?: string;
+    externalDocs?: OpenAPIExternalDocumentation;
+    discriminator?: OpenAPIDiscriminator;
+    nullable?: boolean;
+    oneOf?: OpenAPISchema[];
+    anyOf?: OpenAPISchema[];
+    allOf?: OpenAPISchema[];
+    not?: OpenAPISchema;
+    title?: string;
+    multipleOf?: number;
+    maximum?: number;
+    exclusiveMaximum?: boolean | number;
+    minimum?: number;
+    exclusiveMinimum?: boolean | number;
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+    maxItems?: number;
+    minItems?: number;
+    uniqueItems?: boolean;
+    maxProperties?: number;
+    minProperties?: number;
+    enum?: any[];
+    example?: any;
+    if?: OpenAPISchema;
+    else?: OpenAPISchema;
+    then?: OpenAPISchema;
+    examples?: any[];
+    const?: string;
+    contentEncoding?: string;
+    contentMediaType?: string;
+    prefixItems?: OpenAPISchema[];
+    additionalItems?: OpenAPISchema | boolean;
+}
+export interface OpenAPIDiscriminator {
+    propertyName: string;
+    mapping?: {
+        [name: string]: string;
+    };
+    "x-explicitMappingOnly"?: boolean;
+}
+export interface OpenAPIMediaType {
+    schema?: Referenced<OpenAPISchema>;
+    example?: any;
+    examples?: {
+        [name: string]: Referenced<OpenAPIExample>;
+    };
+    encoding?: {
+        [field: string]: OpenAPIEncoding;
+    };
+}
+export interface OpenAPIEncoding {
+    contentType: string;
+    headers?: {
+        [name: string]: Referenced<OpenAPIHeader>;
+    };
+    style: OpenAPIParameterStyle;
+    explode: boolean;
+    allowReserved: boolean;
+}
+export declare type OpenAPIParameterLocation = "query" | "header" | "path" | "cookie";
+export declare type OpenAPIParameterStyle = "matrix" | "label" | "form" | "simple" | "spaceDelimited" | "pipeDelimited" | "deepObject";
+export interface OpenAPIRequestBody {
+    description?: string;
+    required?: boolean;
+    content: {
+        [mime: string]: OpenAPIMediaType;
+    };
+    "x-examples"?: {
+        [mime: string]: {
+            [name: string]: Referenced<OpenAPIExample>;
+        };
+    };
+    "x-example"?: {
+        [mime: string]: any;
+    };
+}
+export interface OpenAPIResponses {
+    [code: string]: Referenced<OpenAPIResponse>;
+}
+export interface OpenAPIResponse extends Pick<OpenAPIRequestBody, "description" | "x-examples" | "x-example"> {
+    headers?: {
+        [name: string]: Referenced<OpenAPIHeader>;
+    };
+    links?: {
+        [name: string]: Referenced<OpenAPILink>;
+    };
+    content?: {
+        [mime: string]: OpenAPIMediaType;
+    };
+}
+export interface OpenAPILink {
+    $ref?: string;
+}
+export declare type OpenAPIHeader = Omit<OpenAPIParameter, "in" | "name">;
+export interface OpenAPICallback {
+    [name: string]: OpenAPIPath;
+}
+export interface OpenAPIComponents {
+    schemas?: {
+        [name: string]: Referenced<OpenAPISchema>;
+    };
+    responses?: {
+        [name: string]: Referenced<OpenAPIResponse>;
+    };
+    parameters?: {
+        [name: string]: Referenced<OpenAPIParameter>;
+    };
+    examples?: {
+        [name: string]: Referenced<OpenAPIExample>;
+    };
+    requestBodies?: {
+        [name: string]: Referenced<OpenAPIRequestBody>;
+    };
+    headers?: {
+        [name: string]: Referenced<OpenAPIHeader>;
+    };
+    securitySchemes?: {
+        [name: string]: Referenced<OpenAPISecurityScheme>;
+    };
+    links?: {
+        [name: string]: Referenced<OpenAPILink>;
+    };
+    callbacks?: {
+        [name: string]: Referenced<OpenAPICallback>;
+    };
+}
+export interface OpenAPISecurityRequirement {
+    [name: string]: string[];
+}
+export interface OpenAPISecurityScheme {
+    type: "apiKey" | "http" | "oauth2" | "openIdConnect";
+    description?: string;
+    name?: string;
+    in?: "query" | "header" | "cookie";
+    scheme?: string;
+    bearerFormat: string;
+    flows: {
+        implicit?: {
+            refreshUrl?: string;
+            scopes: Record<string, string>;
+            authorizationUrl: string;
+        };
+        password?: {
+            refreshUrl?: string;
+            scopes: Record<string, string>;
+            tokenUrl: string;
+        };
+        clientCredentials?: {
+            refreshUrl?: string;
+            scopes: Record<string, string>;
+            tokenUrl: string;
+        };
+        authorizationCode?: {
+            refreshUrl?: string;
+            scopes: Record<string, string>;
+            tokenUrl: string;
+        };
+    };
+    openIdConnectUrl?: string;
+}
+export interface OpenAPITag {
+    name: string;
+    description?: string;
+    externalDocs?: OpenAPIExternalDocumentation;
+    "x-displayName"?: string;
+}
+export interface OpenAPIExternalDocumentation {
+    description?: string;
+    url: string;
+}
+export interface OpenAPIContact {
+    name?: string;
+    url?: string;
+    email?: string;
+}
+export interface OpenAPILicense {
+    name: string;
+    url?: string;
+    identifier?: string;
+}
+export {};

package/lib/openapi/utils/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types.d.ts

@@ -23,6 +23,8 @@ export interface ApiMetadataBase {
     next?: ApiNavLink;
     id: string;
     unversionedId: string;
+    infoId?: string;
+    infoPath?: string;
     title: string;
     description: string;
     source: string;
@@ -52,6 +54,9 @@ export interface InfoPageMetadata extends ApiMetadataBase {
     type: "info";
     info: ApiInfo;
     markdown?: string;
+    securitySchemes?: {
+        [key: string]: SecuritySchemeObject;
+    };
 }
 export interface TagPageMetadata extends ApiMetadataBase {
     type: "tag";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-361",
+  "version": "0.0.0-366",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,20 +28,21 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.18",
-    "@docusaurus/types": "2.0.0-beta.18",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.21",
+    "@docusaurus/types": "2.0.0-beta.21",
     "@types/fs-extra": "^9.0.13",
     "@types/json-schema": "^7.0.9",
     "@types/lodash": "^4.14.176",
     "utility-types": "^3.10.0"
   },
   "dependencies": {
-    "@docusaurus/mdx-loader": "2.0.0-beta.18",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.18",
-    "@docusaurus/utils": "2.0.0-beta.18",
-    "@docusaurus/utils-validation": "2.0.0-beta.18",
+    "@docusaurus/mdx-loader": "2.0.0-beta.21",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.21",
+    "@docusaurus/utils": "2.0.0-beta.21",
+    "@docusaurus/utils-validation": "2.0.0-beta.21",
     "@paloaltonetworks/openapi-to-postmanv2": "3.1.0-hotfix.1",
     "@paloaltonetworks/postman-collection": "^4.1.0",
+    "@redocly/openapi-core": "^1.0.0-beta.100",
     "@types/js-yaml": "^4.0.5",
     "@types/mustache": "^4.1.2",
     "chalk": "^4.1.2",
@@ -52,6 +53,7 @@
     "json-schema-merge-allof": "^0.8.1",
     "lodash": "^4.17.20",
     "mustache": "^4.2.0",
+    "swagger2openapi": "^7.0.8",
     "webpack": "^5.61.0"
   },
   "peerDependencies": {
@@ -60,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "e87c5db5b36a32b85f7ba0aaea0a0280be498954"
+  "gitHead": "b05ab424dc11297ef08a42bace80791998f70082"
 }

package/src/index.ts

@@ -103,6 +103,9 @@ api: {{{json}}}
 {{#api.method}}
 sidebar_class_name: "{{{api.method}}} api-method"
 {{/api.method}}
+{{#infoPath}}
+info_path: {{{infoPath}}}
+{{/infoPath}}
 ---
 
 {{{markdown}}}
@@ -154,7 +157,9 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
         item.markdown = markdown;
         if (item.type === "api") {
           item.json = JSON.stringify(item.api);
+          if (item.infoId) item.infoPath = `${outputDir}/${item.infoId}`;
         }
+
         const view = render(mdTemplate, item);
         const utils = render(infoMdTemplate, item);
         // eslint-disable-next-line testing-library/render-result-naming-convention

package/src/markdown/createAuthentication.ts

@@ -0,0 +1,160 @@
+/* ============================================================================
+ * 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 { OAuthFlowObject, SecuritySchemeObject } from "../openapi/types";
+import { createDescription } from "./createDescription";
+import { create, guard } from "./utils";
+
+export function createAuthentication(securitySchemes: SecuritySchemeObject) {
+  if (!securitySchemes || !Object.keys(securitySchemes).length) return "";
+
+  const createAuthenticationTable = (securityScheme: any) => {
+    const { bearerFormat, flows, name, scheme, type } = securityScheme;
+
+    const createSecuritySchemeTypeRow = () =>
+      create("tr", {
+        children: [
+          create("th", { children: "Security Scheme Type:" }),
+          create("td", { children: type }),
+        ],
+      });
+
+    const createOAuthFlowRows = () => {
+      const flowRows = Object.entries(flows).map(([flowType, flowObj]) => {
+        const { authorizationUrl, tokenUrl, refreshUrl, scopes } =
+          flowObj as OAuthFlowObject;
+
+        return create("tr", {
+          children: [
+            create("th", { children: `${flowType} OAuth Flow:` }),
+            create("td", {
+              children: [
+                guard(tokenUrl, () =>
+                  create("p", { children: `Token URL: ${tokenUrl}` })
+                ),
+                guard(authorizationUrl, () =>
+                  create("p", {
+                    children: `Authorization URL: ${authorizationUrl}`,
+                  })
+                ),
+                guard(refreshUrl, () =>
+                  create("p", { children: `Refresh URL: ${refreshUrl}` })
+                ),
+                create("span", { children: "Scopes:" }),
+                create("ul", {
+                  children: Object.entries(scopes).map(([scope, description]) =>
+                    create("li", { children: `${scope}: ${description}` })
+                  ),
+                }),
+              ],
+            }),
+          ],
+        });
+      });
+
+      return flowRows.join("");
+    };
+
+    switch (type) {
+      case "apiKey":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  create("tr", {
+                    children: [
+                      create("th", { children: "Header parameter name:" }),
+                      create("td", { children: name }),
+                    ],
+                  }),
+                ],
+              }),
+            }),
+          ],
+        });
+      case "http":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  create("tr", {
+                    children: [
+                      create("th", { children: "HTTP Authorization Scheme:" }),
+                      create("td", { children: scheme }),
+                    ],
+                  }),
+                  create("tr", {
+                    children: [
+                      create("th", { children: "Bearer format:" }),
+                      create("td", { children: bearerFormat }),
+                    ],
+                  }),
+                ],
+              }),
+            }),
+          ],
+        });
+      case "oauth2":
+        return create("div", {
+          children: [
+            create("table", {
+              children: create("tbody", {
+                children: [
+                  createSecuritySchemeTypeRow(),
+                  createOAuthFlowRows(),
+                ],
+              }),
+            }),
+          ],
+        });
+      default:
+        return "";
+    }
+  };
+
+  const formatTabLabel = (str: string) => {
+    const formattedLabel = str
+      .replace(/(_|-)/g, " ")
+      .trim()
+      .replace(/\w\S*/g, (str) => str.charAt(0).toUpperCase() + str.substr(1))
+      .replace(/([a-z])([A-Z])/g, "$1 $2")
+      .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2");
+
+    const isOAuth = formattedLabel.toLowerCase().includes("oauth2");
+    const isApiKey = formattedLabel.toLowerCase().includes("api");
+
+    return isOAuth ? "OAuth 2.0" : isApiKey ? "API Key" : formattedLabel;
+  };
+
+  return create("div", {
+    children: [
+      create("h2", {
+        children: "Authentication",
+        id: "authentication",
+        style: { marginBottom: "1rem" },
+      }),
+      create("Tabs", {
+        children: Object.entries(securitySchemes).map(
+          ([schemeType, schemeObj]) =>
+            create("TabItem", {
+              label: formatTabLabel(schemeType),
+              value: `${schemeType}`,
+              children: [
+                createDescription(schemeObj.description),
+                createAuthenticationTable(schemeObj),
+              ],
+            })
+        ),
+      }),
+    ],
+    style: { marginBottom: "2rem" },
+  });
+}

package/src/markdown/index.ts

@@ -7,8 +7,13 @@
 
 import { escape } from "lodash";
 
-import { ContactObject, LicenseObject } from "../openapi/types";
+import {
+  ContactObject,
+  LicenseObject,
+  SecuritySchemeObject,
+} from "../openapi/types";
 import { ApiPageMetadata, InfoPageMetadata, TagPageMetadata } from "../types";
+import { createAuthentication } from "./createAuthentication";
 import { createContactInfo } from "./createContactInfo";
 import { createDeprecationNotice } from "./createDeprecationNotice";
 import { createDescription } from "./createDescription";
@@ -50,11 +55,15 @@ export function createApiPageMD({
 
 export function createInfoPageMD({
   info: { title, version, description, contact, license, termsOfService },
+  securitySchemes,
 }: InfoPageMetadata) {
   return render([
+    `import Tabs from "@theme/Tabs";\n`,
+    `import TabItem from "@theme/TabItem";\n`,
     createVersionBadge(version),
     `# ${escape(title)}\n\n`,
     createDescription(description),
+    createAuthentication(securitySchemes as unknown as SecuritySchemeObject),
     createContactInfo(contact as ContactObject),
     createTermsOfService(termsOfService),
     createLicense(license as LicenseObject),

package/src/openapi/openapi.test.ts

@@ -26,12 +26,6 @@ describe("openapi", () => {
       const yaml = results.find((x) => x.source.endsWith("openapi.yaml"));
       expect(yaml).toBeTruthy();
       expect(yaml?.sourceDirName).toBe(".");
-      const froyo = results.find((x) => x.source.endsWith("froyo.yaml"));
-      expect(froyo).toBeTruthy();
-      expect(froyo?.sourceDirName).toBe("yogurtstore");
-      const nested = results.find((x) => x.source.endsWith("nested.yaml"));
-      expect(nested).toBeTruthy();
-      expect(nested?.sourceDirName).toBe("yogurtstore/nested");
     });
   });
 });

package/src/openapi/openapi.ts

@@ -13,7 +13,6 @@ import sdk from "@paloaltonetworks/postman-collection";
 import Collection from "@paloaltonetworks/postman-collection";
 import chalk from "chalk";
 import fs from "fs-extra";
-import yaml from "js-yaml";
 import JsonRefs from "json-refs";
 import { kebabCase } from "lodash";
 
@@ -26,6 +25,7 @@ import {
 } from "../types";
 import { sampleFromSchema } from "./createExample";
 import { OpenApiObject, OpenApiObjectWithRef, TagObject } from "./types";
+import { loadAndBundleSpec } from "./utils/loadAndBundleSpec";
 
 /**
  * Finds any reference objects in the OpenAPI definition and resolves them to a finalized value.
@@ -87,6 +87,7 @@ function createItems(
 ): ApiMetadata[] {
   // TODO: Find a better way to handle this
   let items: PartialPage<ApiMetadata>[] = [];
+  const infoId = kebabCase(openapiData.info.title);
 
   if (sidebarOptions?.categoryLinkSource === "tag") {
     // Only create an tag pages if categoryLinkSource set to tag.
@@ -119,7 +120,6 @@ function createItems(
 
   if (openapiData.info.description) {
     // Only create an info page if we have a description.
-    const infoId = kebabCase(openapiData.info.title);
     const infoPage: PartialPage<InfoPageMetadata> = {
       type: "info",
       id: infoId,
@@ -128,6 +128,7 @@ function createItems(
       description: openapiData.info.description,
       slug: "/" + infoId,
       frontMatter: {},
+      securitySchemes: openapiData.components?.securitySchemes,
       info: {
         ...openapiData.info,
         tags: openapiData.tags?.map((tagName) =>
@@ -183,6 +184,7 @@ function createItems(
       const apiPage: PartialPage<ApiPageMetadata> = {
         type: "api",
         id: baseId,
+        infoId: infoId ?? "",
         unversionedId: baseId,
         title: title,
         description: description ?? "",
@@ -258,14 +260,16 @@ export async function readOpenapiFiles(
     const allFiles = await Globby(["**/*.{json,yaml,yml}"], {
       cwd: openapiPath,
       ignore: GlobExcludeDefault,
+      deep: 1,
     });
     const sources = allFiles.filter((x) => !x.includes("_category_")); // todo: regex exclude?
     return Promise.all(
       sources.map(async (source) => {
         // TODO: make a function for this
         const fullPath = path.join(openapiPath, source);
-        const openapiString = await fs.readFile(fullPath, "utf-8");
-        const data = yaml.load(openapiString) as OpenApiObjectWithRef;
+        const data = (await loadAndBundleSpec(
+          fullPath
+        )) as OpenApiObjectWithRef;
         return {
           source: fullPath, // This will be aliased in process.
           sourceDirName: path.dirname(source),
@@ -274,8 +278,7 @@ export async function readOpenapiFiles(
       })
     );
   }
-  const openapiString = await fs.readFile(openapiPath, "utf-8");
-  const data = yaml.load(openapiString) as OpenApiObjectWithRef;
+  const data = (await loadAndBundleSpec(openapiPath)) as OpenApiObjectWithRef;
   return [
     {
       source: openapiPath, // This will be aliased in process.