docusaurus-plugin-openapi-docs 1.0.2 → 1.0.3

package/src/openapi/openapi.ts

@@ -13,13 +13,20 @@ 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";
 
-import { ApiMetadata, ApiPageMetadata, InfoPageMetadata } from "../types";
+import { isURL } from "../index";
+import {
+  ApiMetadata,
+  ApiPageMetadata,
+  InfoPageMetadata,
+  SidebarOptions,
+  TagPageMetadata,
+} 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.
@@ -75,13 +82,45 @@ async function createPostmanCollection(
 
 type PartialPage<T> = Omit<T, "permalink" | "source" | "sourceDirName">;
 
-function createItems(openapiData: OpenApiObject): ApiMetadata[] {
+function createItems(
+  openapiData: OpenApiObject,
+  sidebarOptions: SidebarOptions
+): 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.
+    const tags: TagObject[] = openapiData.tags ?? [];
+    // eslint-disable-next-line array-callback-return
+    tags
+      .filter((tag) => !tag.description?.includes("SchemaDefinition"))
+      // eslint-disable-next-line array-callback-return
+      .map((tag) => {
+        const description = getTagDisplayName(
+          tag.name!,
+          openapiData.tags ?? []
+        );
+        const tagId = kebabCase(tag.name);
+        const tagPage: PartialPage<TagPageMetadata> = {
+          type: "tag",
+          id: tagId,
+          unversionedId: tagId,
+          title: description ?? "",
+          description: description ?? "",
+          slug: "/" + tagId,
+          frontMatter: {},
+          tag: {
+            ...tag,
+          },
+        };
+        items.push(tagPage);
+      });
+  }
 
-  // Only create an info page if we have a description.
   if (openapiData.info.description) {
-    const infoId = kebabCase(openapiData.info.title);
+    // Only create an info page if we have a description.
     const infoPage: PartialPage<InfoPageMetadata> = {
       type: "info",
       id: infoId,
@@ -90,6 +129,7 @@ function createItems(openapiData: OpenApiObject): ApiMetadata[] {
       description: openapiData.info.description,
       slug: "/" + infoId,
       frontMatter: {},
+      securitySchemes: openapiData.components?.securitySchemes,
       info: {
         ...openapiData.info,
         tags: openapiData.tags?.map((tagName) =>
@@ -145,6 +185,7 @@ function createItems(openapiData: OpenApiObject): ApiMetadata[] {
       const apiPage: PartialPage<ApiPageMetadata> = {
         type: "api",
         id: baseId,
+        infoId: infoId ?? "",
         unversionedId: baseId,
         title: title,
         description: description ?? "",
@@ -186,7 +227,7 @@ function bindCollectionToApiItems(
       .replace(/:([a-z0-9-_]+)/gi, "{$1}"); // replace "/:variableName" with "/{variableName}"
 
     const apiItem = items.find((item) => {
-      if (item.type === "info") {
+      if (item.type === "info" || item.type === "tag") {
         return false;
       }
       return item.api.path === path && item.api.method === method;
@@ -208,36 +249,39 @@ export async function readOpenapiFiles(
   openapiPath: string,
   _options: {}
 ): Promise<OpenApiFiles[]> {
-  const stat = await fs.lstat(openapiPath);
-  if (stat.isDirectory()) {
-    console.warn(
-      chalk.yellow(
-        "WARNING: Loading a directory of OpenAPI definitions is experimental and subject to unannounced breaking changes."
-      )
-    );
-
-    // TODO: Add config for inlcude/ignore
-    const allFiles = await Globby(["**/*.{json,yaml,yml}"], {
-      cwd: openapiPath,
-      ignore: GlobExcludeDefault,
-    });
-    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;
-        return {
-          source: fullPath, // This will be aliased in process.
-          sourceDirName: path.dirname(source),
-          data,
-        };
-      })
-    );
+  if (!isURL(openapiPath)) {
+    const stat = await fs.lstat(openapiPath);
+    if (stat.isDirectory()) {
+      console.warn(
+        chalk.yellow(
+          "WARNING: Loading a directory of OpenAPI definitions is experimental and subject to unannounced breaking changes."
+        )
+      );
+
+      // TODO: Add config for inlcude/ignore
+      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 data = (await loadAndBundleSpec(
+            fullPath
+          )) as OpenApiObjectWithRef;
+          return {
+            source: fullPath, // This will be aliased in process.
+            sourceDirName: path.dirname(source),
+            data,
+          };
+        })
+      );
+    }
   }
-  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.
@@ -248,10 +292,11 @@ export async function readOpenapiFiles(
 }
 
 export async function processOpenapiFiles(
-  files: OpenApiFiles[]
+  files: OpenApiFiles[],
+  sidebarOptions: SidebarOptions
 ): Promise<[ApiMetadata[], TagObject[]]> {
   const promises = files.map(async (file) => {
-    const processedFile = await processOpenapiFile(file.data);
+    const processedFile = await processOpenapiFile(file.data, sidebarOptions);
     const itemsObjectsArray = processedFile[0].map((item) => ({
       ...item,
     }));
@@ -271,11 +316,12 @@ export async function processOpenapiFiles(
 }
 
 export async function processOpenapiFile(
-  openapiDataWithRefs: OpenApiObjectWithRef
+  openapiDataWithRefs: OpenApiObjectWithRef,
+  sidebarOptions: SidebarOptions
 ): Promise<[ApiMetadata[], TagObject[]]> {
   const openapiData = await resolveRefs(openapiDataWithRefs);
   const postmanCollection = await createPostmanCollection(openapiData);
-  const items = createItems(openapiData);
+  const items = createItems(openapiData, sidebarOptions);
 
   bindCollectionToApiItems(items, postmanCollection);
 

package/src/openapi/utils/loadAndBundleSpec.ts

@@ -0,0 +1,62 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+// @ts-nocheck
+
+import type { Source, Document } from "@redocly/openapi-core";
+import { bundle } from "@redocly/openapi-core/lib/bundle";
+import type { ResolvedConfig } from "@redocly/openapi-core/lib/config";
+import { Config } from "@redocly/openapi-core/lib/config/config";
+import { convertObj } from "swagger2openapi";
+
+import { OpenAPISpec } from "./types";
+
+export async function loadAndBundleSpec(
+  specUrlOrObject: object | string
+): Promise<OpenAPISpec> {
+  const config = new Config({} as ResolvedConfig);
+  const bundleOpts = {
+    config,
+    base: process.cwd(),
+  };
+
+  if (typeof specUrlOrObject === "object" && specUrlOrObject !== null) {
+    bundleOpts["doc"] = {
+      source: { absoluteRef: "" } as Source,
+      parsed: specUrlOrObject,
+    } as Document;
+  } else {
+    bundleOpts["ref"] = specUrlOrObject;
+  }
+
+  // Force dereference ?
+  // bundleOpts["dereference"] = true;
+
+  const {
+    bundle: { parsed },
+  } = await bundle(bundleOpts);
+  return parsed.swagger !== undefined ? convertSwagger2OpenAPI(parsed) : parsed;
+}
+
+export function convertSwagger2OpenAPI(spec: any): Promise<OpenAPISpec> {
+  console.warn(
+    "[ReDoc Compatibility mode]: Converting OpenAPI 2.0 to OpenAPI 3.0"
+  );
+  return new Promise<OpenAPISpec>((resolve, reject) =>
+    convertObj(
+      spec,
+      { patch: true, warnOnly: true, text: "{}", anchors: true },
+      (err, res) => {
+        // TODO: log any warnings
+        if (err) {
+          return reject(err);
+        }
+        resolve(res && (res.openapi as any));
+      }
+    )
+  );
+}

package/src/openapi/utils/types.ts

@@ -0,0 +1,303 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+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 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[]; // deprecated
+}
+
+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 type OpenAPIParameterLocation = "query" | "header" | "path" | "cookie";
+export 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 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;
+}

package/src/sidebars/index.ts

@@ -7,6 +7,7 @@
 
 import {
   ProcessedSidebar,
+  SidebarItemCategory,
   SidebarItemCategoryLinkConfig,
   SidebarItemDoc,
 } from "@docusaurus/plugin-content-docs/src/sidebars/types";
@@ -99,7 +100,9 @@ function groupByTags(
   const tagged = apiTags
     .map((tag) => {
       // Map info object to tag
-      const infoObject = intros.find((i) => i.tags.includes(tag));
+      const taggedInfoObject = intros.find((i) =>
+        i.tags ? i.tags.includes(tag) : undefined
+      );
       const tagObject = tags.flat().find(
         (t) =>
           (tag === t.name || tag === t["x-displayName"]) ?? {
@@ -110,21 +113,19 @@ function groupByTags(
 
       // TODO: perhaps move this into a getLinkConfig() function
       let linkConfig = undefined;
-      if (infoObject !== undefined && categoryLinkSource === "info") {
+      if (taggedInfoObject !== undefined && categoryLinkSource === "info") {
         linkConfig = {
           type: "doc",
-          id: `${basePath}/${infoObject.id}`,
+          id: `${basePath}/${taggedInfoObject.id}`,
         } as SidebarItemCategoryLinkConfig;
       }
 
       // TODO: perhaps move this into a getLinkConfig() function
       if (tagObject !== undefined && categoryLinkSource === "tag") {
-        const linkDescription = tagObject?.description;
+        const tagId = kebabCase(tagObject.name);
         linkConfig = {
-          type: "generated-index" as "generated-index",
-          title: tag,
-          description: linkDescription,
-          slug: "/category/" + kebabCase(tag),
+          type: "doc",
+          id: `${basePath}/${tagId}`,
         } as SidebarItemCategoryLinkConfig;
       }
 
@@ -150,18 +151,24 @@ function groupByTags(
     })
     .filter((item) => item.items.length > 0); // Filter out any categories with no items.
 
-  // TODO: determine how we want to handle these
-  // const untagged = [
-  //   {
-  //     type: "category" as const,
-  //     label: "UNTAGGED",
-  //     collapsible: sidebarCollapsible,
-  //     collapsed: sidebarCollapsed,
-  //     items: apiItems
-  //       .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-  //       .map(createDocItem),
-  //   },
-  // ];
+  // Handle items with no tag
+  const untaggedItems = apiItems
+    .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+    .map(createDocItem);
+  let untagged: SidebarItemCategory[] = [];
+  if (untaggedItems.length > 0) {
+    untagged = [
+      {
+        type: "category" as const,
+        label: "UNTAGGED",
+        collapsible: sidebarCollapsible!,
+        collapsed: sidebarCollapsed!,
+        items: apiItems
+          .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+          .map(createDocItem),
+      },
+    ];
+  }
 
   // Shift root intro doc to top of sidebar
   // TODO: Add input validation for categoryLinkSource options
@@ -169,7 +176,7 @@ function groupByTags(
     tagged.unshift(rootIntroDoc as any);
   }
 
-  return [...tagged];
+  return [...tagged, ...untagged];
 }
 
 export default function generateSidebarSlice(
@@ -179,7 +186,7 @@ export default function generateSidebarSlice(
   tags: TagObject[]
 ) {
   let sidebarSlice: ProcessedSidebar = [];
-  if (sidebarOptions.groupPathsBy === "tags") {
+  if (sidebarOptions.groupPathsBy === "tag") {
     sidebarSlice = groupByTags(
       api as ApiPageMetadata[],
       sidebarOptions,

package/src/types.ts

@@ -11,6 +11,7 @@ import {
   InfoObject,
   OperationObject,
   SecuritySchemeObject,
+  TagObject,
 } from "./openapi/types";
 
 export type {
@@ -38,7 +39,7 @@ export interface LoadedContent {
   // loadedDocs: DocPageMetadata[]; TODO: cleanup
 }
 
-export type ApiMetadata = ApiPageMetadata | InfoPageMetadata;
+export type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata;
 
 export interface ApiMetadataBase {
   sidebar?: string;
@@ -47,6 +48,8 @@ export interface ApiMetadataBase {
   //
   id: string; // TODO legacy versioned id => try to remove
   unversionedId: string; // TODO new unversioned id => try to rename to "id"
+  infoId?: string;
+  infoPath?: string;
   title: string;
   description: string;
   source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
@@ -79,6 +82,15 @@ export interface InfoPageMetadata extends ApiMetadataBase {
   type: "info";
   info: ApiInfo;
   markdown?: string;
+  securitySchemes?: {
+    [key: string]: SecuritySchemeObject;
+  };
+}
+
+export interface TagPageMetadata extends ApiMetadataBase {
+  type: "tag";
+  tag: TagObject;
+  markdown?: string;
 }
 
 export type ApiInfo = InfoObject;