docusaurus-plugin-openapi-docs 1.0.0 → 1.0.3

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/{markdown/createRequestBodyTable.js → openapi/utils/types.js}

@@ -6,9 +6,3 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRequestBodyTable = void 0;
-const createSchemaTable_1 = require("./createSchemaTable");
-function createRequestBodyTable({ title, body }) {
-    return (0, createSchemaTable_1.createSchemaTable)({ title, body });
-}
-exports.createRequestBodyTable = createRequestBodyTable;

package/lib/sidebars/index.d.ts

@@ -1,3 +1,4 @@
 import { ProcessedSidebar } from "@docusaurus/plugin-content-docs/src/sidebars/types";
+import { TagObject } from "../openapi/types";
 import type { SidebarOptions, APIOptions, ApiMetadata } from "../types";
-export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[]): ProcessedSidebar;
+export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[], tags: TagObject[]): ProcessedSidebar;

package/lib/sidebars/index.js

@@ -10,25 +10,29 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const clsx_1 = __importDefault(require("clsx"));
+const lodash_1 = require("lodash");
 const uniq_1 = __importDefault(require("lodash/uniq"));
 function isApiItem(item) {
     return item.type === "api";
 }
-function groupByTags(items, sidebarOptions, options) {
-    // TODO: Figure out how to handle these
-    // const intros = items.filter(isInfoItem).map((item) => {
-    //   return {
-    //     type: "link" as const,
-    //     label: item.title,
-    //     href: item.permalink,
-    //     docId: item.id,
-    //   };
-    // });
+function isInfoItem(item) {
+    return item.type === "info";
+}
+function groupByTags(items, sidebarOptions, options, tags) {
     const { outputDir } = options;
-    const { sidebarCollapsed, sidebarCollapsible, customProps } = sidebarOptions;
+    const { sidebarCollapsed, sidebarCollapsible, customProps, categoryLinkSource, } = sidebarOptions;
     const apiItems = items.filter(isApiItem);
+    const infoItems = items.filter(isInfoItem);
+    const intros = infoItems.map((item) => {
+        return {
+            id: item.id,
+            title: item.title,
+            description: item.description,
+            tags: item.info.tags,
+        };
+    });
     // TODO: make sure we only take the first tag
-    const tags = (0, uniq_1.default)(apiItems
+    const apiTags = (0, uniq_1.default)(apiItems
         .flatMap((item) => item.api.tags)
         .filter((item) => !!item));
     // TODO: optimize this or make it a function
@@ -51,11 +55,54 @@ function groupByTags(items, sidebarOptions, options) {
             }, item.api.method),
         };
     }
-    const tagged = tags
+    let rootIntroDoc = undefined;
+    if (infoItems.length === 1) {
+        const infoItem = infoItems[0];
+        const id = infoItem.id;
+        rootIntroDoc = {
+            type: "doc",
+            id: `${basePath}/${id}`,
+        };
+    }
+    const tagged = apiTags
         .map((tag) => {
+        // Map info object to tag
+        const taggedInfoObject = intros.find((i) => i.tags ? i.tags.includes(tag) : undefined);
+        const tagObject = tags.flat().find((t) => {
+            var _a;
+            return (_a = (tag === t.name || tag === t["x-displayName"])) !== null && _a !== void 0 ? _a : {
+                name: tag,
+                description: `${tag} Index`,
+            };
+        });
+        // TODO: perhaps move this into a getLinkConfig() function
+        let linkConfig = undefined;
+        if (taggedInfoObject !== undefined && categoryLinkSource === "info") {
+            linkConfig = {
+                type: "doc",
+                id: `${basePath}/${taggedInfoObject.id}`,
+            };
+        }
+        // TODO: perhaps move this into a getLinkConfig() function
+        if (tagObject !== undefined && categoryLinkSource === "tag") {
+            const tagId = (0, lodash_1.kebabCase)(tagObject.name);
+            linkConfig = {
+                type: "doc",
+                id: `${basePath}/${tagId}`,
+            };
+        }
+        // Default behavior
+        if (categoryLinkSource === undefined) {
+            linkConfig = {
+                type: "generated-index",
+                title: tag,
+                slug: "/category/" + (0, lodash_1.kebabCase)(tag),
+            };
+        }
         return {
             type: "category",
             label: tag,
+            link: linkConfig,
             collapsible: sidebarCollapsible,
             collapsed: sidebarCollapsed,
             items: apiItems
@@ -64,25 +111,35 @@ function groupByTags(items, sidebarOptions, options) {
         };
     })
         .filter((item) => item.items.length > 0); // Filter out any categories with no items.
-    // const untagged = [
-    //   // TODO: determine if needed and how
-    //   {
-    //     type: "category" as const,
-    //     label: "UNTAGGED",
-    //     // collapsible: options.sidebarCollapsible, TODO: add option
-    //     // collapsed: options.sidebarCollapsed, TODO: add option
-    //     items: apiItems
-    //       //@ts-ignore
-    //       .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
-    //       .map(createDocItem),
-    //   },
-    // ];
-    return [...tagged];
+    // Handle items with no tag
+    const untaggedItems = apiItems
+        .filter(({ api }) => api.tags === undefined || api.tags.length === 0)
+        .map(createDocItem);
+    let untagged = [];
+    if (untaggedItems.length > 0) {
+        untagged = [
+            {
+                type: "category",
+                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
+    if (rootIntroDoc && categoryLinkSource !== "info") {
+        tagged.unshift(rootIntroDoc);
+    }
+    return [...tagged, ...untagged];
 }
-function generateSidebarSlice(sidebarOptions, options, api) {
+function generateSidebarSlice(sidebarOptions, options, api, tags) {
     let sidebarSlice = [];
-    if (sidebarOptions.groupPathsBy === "tags") {
-        sidebarSlice = groupByTags(api, sidebarOptions, options);
+    if (sidebarOptions.groupPathsBy === "tag") {
+        sidebarSlice = groupByTags(api, sidebarOptions, options, tags);
     }
     return sidebarSlice;
 }

package/lib/types.d.ts

@@ -1,5 +1,5 @@
-import type { Request } from "@paloaltonetworks/postman-collection";
-import { InfoObject, OperationObject, SecuritySchemeObject } from "./openapi/types";
+import type Request from "@paloaltonetworks/postman-collection";
+import { InfoObject, OperationObject, SecuritySchemeObject, TagObject } from "./openapi/types";
 export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs-types";
 export interface PluginOptions {
     id?: string;
@@ -16,13 +16,15 @@ export interface APIOptions {
 export interface LoadedContent {
     loadedApi: ApiMetadata[];
 }
-export declare type ApiMetadata = ApiPageMetadata | InfoPageMetadata;
+export declare type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata;
 export interface ApiMetadataBase {
     sidebar?: string;
     previous?: ApiNavLink;
     next?: ApiNavLink;
     id: string;
     unversionedId: string;
+    infoId?: string;
+    infoPath?: string;
     title: string;
     description: string;
     source: string;
@@ -52,6 +54,14 @@ 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 declare type ApiInfo = InfoObject;
 export interface ApiNavLink {
@@ -60,6 +70,7 @@ export interface ApiNavLink {
 }
 export interface SidebarOptions {
     groupPathsBy?: string;
+    categoryLinkSource?: string;
     customProps?: {
         [key: string]: unknown;
     };

package/package.json

@@ -1,18 +1,25 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "license": "MIT",
+  "keywords": [
+    "openapi",
+    "documentation",
+    "docusaurus",
+    "websites",
+    "plugin"
+  ],
   "publishConfig": {
     "access": "public"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi.git",
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi-docs.git",
     "directory": "packages/docusaurus-plugin-openapi-docs"
   },
   "bugs": {
-    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi/issues"
+    "url": "https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues"
   },
   "main": "lib/index.js",
   "types": "src/plugin-openapi.d.ts",
@@ -21,21 +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",
-    "@types/postman-collection": "^3.5.7",
     "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",
@@ -46,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": {
@@ -54,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "8905a438e86fc0a5cb9f033fb1b29630ff059af8"
+  "gitHead": "618a438ec42148f525fb92cb11d291ce50d2ad06"
 }