@visulima/jsdoc-open-api 1.2.0 → 1.2.2

package/src/exported.d.ts

@@ -1,266 +0,0 @@
-declare function openapi(options?: ParserOptions): OpenApiObject;
-
-export default openapi;
-
-export interface ParserOptions {
-    cwd: string;
-    extension?: string[];
-    include?: string[];
-    exclude?: string[];
-    excludeNodeModules?: boolean;
-    verbose?: boolean;
-}
-
-export interface BaseDefinition {
-    openapi: string;
-    info: InfoObject;
-    servers?: ServerObject[];
-    paths?: PathsObject;
-    components?: ComponentsObject;
-    security?: SecurityRequirementObject[];
-    tags?: TagObject[];
-    externalDocs?: ExternalDocumentationObject;
-}
-
-export interface OpenApiObject extends BaseDefinition {
-    paths: PathsObject;
-}
-
-export interface InfoObject {
-    title: string;
-    version: string;
-    description?: string;
-    termsOfService?: string;
-    contact?: ContactObject;
-    license?: LicenseObject;
-}
-
-export interface ContactObject {
-    name?: string;
-    url?: string;
-    email?: string;
-}
-
-export interface LicenseObject {
-    name: string;
-    url?: string;
-}
-
-export interface ServerObject {
-    url: string;
-    description?: string;
-    variables?: Map<ServerVariable>;
-}
-
-export interface ServerVariable {
-    default: string;
-    enum?: string[];
-    description?: string;
-}
-
-export interface ComponentsObject {
-    schemas?: Map<SchemaObject | ReferenceObject>;
-    responses?: Map<ResponseObject | ReferenceObject>;
-    parameters?: Map<ParameterObject | ReferenceObject>;
-    examples?: Map<ExampleObject | ReferenceObject>;
-    requestBodies?: Map<RequestBodyObject | ReferenceObject>;
-    headers?: Map<HeaderObject | ReferenceObject>;
-    securitySchemes?: Map<
-    ApiKeySecuritySchemeObject | HttpSecuritySchemeObject | Oauth2SecuritySchemeObject | OpenIdConnectSecuritySchemeObject | ReferenceObject
-    >;
-    links?: Map<LinkObject | ReferenceObject>;
-    callbacks?: Map<CallbackObject | ReferenceObject>;
-}
-
-export interface PathsObject {
-    [path: string]: PathItemObject;
-}
-
-export interface PathItemObject {
-    $ref?: string;
-    summary?: string;
-    description?: string;
-    get?: OperationObject;
-    put?: OperationObject;
-    post?: OperationObject;
-    delete?: OperationObject;
-    options?: OperationObject;
-    head?: OperationObject;
-    patch?: OperationObject;
-    trace?: OperationObject;
-    servers?: ServerObject[];
-    parameters?: (ParameterObject | ReferenceObject)[];
-}
-
-export interface OperationObject {
-    responses: ResponsesObject;
-    tags?: string[];
-    summary?: string;
-    description?: string;
-    externalDocs?: ExternalDocumentationObject;
-    operationId?: string;
-    parameters?: (ParameterObject | ReferenceObject)[];
-    requestBody?: RequestBodyObject | ReferenceObject;
-    callbacks?: Map<CallbackObject | ReferenceObject>;
-    deprecated?: boolean;
-    security?: SecurityRequirementObject[];
-    servers?: ServerObject[];
-}
-
-export interface ExternalDocumentationObject {
-    url: string;
-    description?: string;
-}
-
-export interface ParameterObject {
-    name: string;
-    in: string;
-    description?: string;
-    required?: boolean;
-    deprecated?: boolean;
-    allowEmptyValue?: boolean;
-    //
-    style?: string;
-    explode?: string;
-    allowReserved?: boolean;
-    schema?: SchemaObject | ReferenceObject;
-    example?: any;
-    examples?: Map<ExampleObject | ReferenceObject>;
-    //
-    content?: Map<MediaTypeObject>;
-    // ignoring stylings: matrix, label, form, simple, spaceDelimited,
-    // pipeDelimited and deepObject
-}
-
-export interface RequestBodyObject {
-    content: Map<MediaTypeObject>;
-    description?: string;
-    required?: boolean;
-}
-
-export interface MediaTypeObject {
-    schema?: SchemaObject | ReferenceObject;
-    example?: any;
-    examples?: Map<ExampleObject | ReferenceObject>;
-    encoding?: Map<EncodingObject>;
-}
-
-export interface EncodingObject {
-    contentType?: string;
-    headers?: Map<HeaderObject | ReferenceObject>;
-    style?: string;
-    explode?: boolean;
-    allowReserved?: boolean;
-}
-
-export interface ResponsesObject {
-    [code: string]: ResponseObject | ReferenceObject;
-}
-
-export interface ResponseObject {
-    description: string;
-    headers?: Map<HeaderObject | ReferenceObject>;
-    content?: Map<MediaTypeObject>;
-    links?: Map<LinkObject | ReferenceObject>;
-}
-
-export interface CallbackObject {
-    [expression: string]: PathItemObject;
-}
-
-export interface ExampleObject {
-    summary?: string;
-    description?: string;
-    value?: any;
-    externalValue?: string;
-}
-
-export interface LinkObject {
-    operationRef?: string;
-    operationId?: string;
-    parameters?: Map<any>;
-    requestBody?: any;
-    description?: string;
-    server?: ServerObject;
-}
-
-export interface HeaderObject {
-    description?: string;
-    required?: boolean;
-    deprecated?: boolean;
-    allowEmptyValue?: boolean;
-    //
-    style?: string;
-    explode?: string;
-    allowReserved?: boolean;
-    schema?: SchemaObject | ReferenceObject;
-    example?: any;
-    examples?: Map<ExampleObject | ReferenceObject>;
-    //
-    content?: Map<MediaTypeObject>;
-    // ignoring stylings: matrix, label, form, simple, spaceDelimited,
-    // pipeDelimited and deepObject
-}
-
-export interface TagObject {
-    name: string;
-    description?: string;
-    externalDocs?: ExternalDocumentationObject;
-}
-
-export interface ReferenceObject {
-    $ref: string;
-}
-
-// TODO: this could be expanded on.
-export interface SchemaObject {
-    [key: string]: any;
-}
-
-export interface ApiKeySecuritySchemeObject {
-    type: string;
-    description?: string;
-    name: string;
-    in: string;
-}
-
-export interface HttpSecuritySchemeObject {
-    type: string;
-    description?: string;
-    scheme: string;
-    bearerFormat?: string;
-}
-
-export interface Oauth2SecuritySchemeObject {
-    type: string;
-    description?: string;
-    flows: OAuthFlowsObject;
-}
-
-export interface OpenIdConnectSecuritySchemeObject {
-    type: string;
-    description?: string;
-    openIdConnectUrl: string;
-}
-
-export interface OAuthFlowsObject {
-    implicit?: OAuthFlowObject;
-    password?: OAuthFlowObject;
-    clientCredentials?: OAuthFlowObject;
-    authorizationCode?: OAuthFlowObject;
-}
-
-export interface OAuthFlowObject {
-    authorizationUrl?: string; // required for some?
-    tokenUrl?: string; // required for some?
-    refreshUrl: string;
-    scopes: Map<string>;
-}
-
-export interface SecurityRequirementObject {
-    [name: string]: string[];
-}
-
-export interface Map<T> {
-    [key: string]: T;
-}

package/src/index.ts

@@ -1,7 +0,0 @@
-export { default as SpecBuilder } from "./spec-builder";
-export { default as parseFile } from "./parse-file";
-export { default as yamlLoc } from "./util/yaml-loc";
-export type { BaseDefinition, OpenApiObject } from "./exported";
-export { default as SwaggerCompilerPlugin } from "./webpack/swagger-compiler-plugin";
-export { default as jsDocumentCommentsToOpenApi } from "./jsdoc/comments-to-open-api";
-export { default as swaggerJsDocumentCommentsToOpenApi } from "./swagger-jsdoc/comments-to-open-api";

package/src/jsdoc/comments-to-open-api.ts

@@ -1,402 +0,0 @@
-import type { Spec } from "comment-parser";
-import { parse as parseComments } from "comment-parser";
-import mergeWith from "lodash.mergewith";
-
-import { OpenApiObject, PathsObject } from "../exported";
-import customizer from "../util/customizer";
-
-// The security object has a bizare setup...
-function fixSecurityObject(thing: any) {
-    if (thing.security) {
-        // eslint-disable-next-line no-param-reassign
-        thing.security = Object.keys(thing.security).map((s) => {
-            return {
-                [s]: thing.security[s],
-            };
-        });
-    }
-}
-
-const primitiveTypes = new Set(["integer", "number", "string", "boolean", "object", "array"]);
-
-const formatMap: { [key: string]: string } = {
-    int32: "integer",
-    int64: "integer",
-    float: "number",
-    double: "number",
-    date: "string",
-    "date-time": "string",
-    password: "string",
-    byte: "string",
-    binary: "string",
-};
-
-function parseDescription(tag: any) {
-    const rawType = tag.type;
-    const isArray = rawType && rawType.endsWith("[]");
-
-    let parsedType;
-
-    if (rawType) {
-        parsedType = rawType.replace(/\[]$/, "");
-    }
-
-    const isPrimitive = primitiveTypes.has(parsedType);
-    const isFormat = Object.keys(formatMap).includes(parsedType);
-
-    let defaultValue;
-
-    if (tag.default) {
-        switch (parsedType) {
-            case "integer":
-            case "int32":
-            case "int64": {
-                defaultValue = Number.parseInt(tag.default, 10);
-                break;
-            }
-            case "number":
-            case "double":
-            case "float": {
-                defaultValue = Number.parseFloat(tag.default);
-                break;
-            }
-            default: {
-                defaultValue = tag.default;
-                break;
-            }
-        }
-    }
-
-    let rootType;
-
-    if (isPrimitive) {
-        rootType = { type: parsedType, default: defaultValue };
-    } else if (isFormat) {
-        rootType = {
-            type: formatMap[parsedType],
-            format: parsedType,
-            default: defaultValue,
-        };
-    } else {
-        rootType = { $ref: `#/components/schemas/${parsedType}` };
-    }
-
-    let schema: undefined | object = isArray
-        ? {
-            type: "array",
-            items: {
-                ...rootType,
-            },
-        }
-        : {
-            ...rootType,
-        };
-
-    if (parsedType === undefined) {
-        schema = undefined;
-    }
-
-    // remove the optional dash from the description.
-    let description = tag.description.trim().replace(/^- /, "");
-
-    if (description === "") {
-        description = undefined;
-    }
-
-    return {
-        name: tag.name,
-        description,
-        required: !tag.optional,
-        schema,
-        rawType,
-    };
-}
-
-// @ts-ignore
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function tagsToObjects(tags: Spec[], verbose?: boolean) {
-    return tags.map((tag) => {
-        const parsedResponse = parseDescription(tag);
-
-        // Some ops only have a `description`, merge `name` and `description`
-        // for these.
-        let nameAndDescription = "";
-
-        if (parsedResponse.name) {
-            nameAndDescription += parsedResponse.name;
-        }
-
-        if (parsedResponse.description) {
-            nameAndDescription += ` ${parsedResponse.description.trim()}`;
-        }
-
-        switch (tag.tag) {
-            case "operationId":
-            case "summary":
-            case "description": {
-                return { [tag.tag]: nameAndDescription };
-            }
-
-            case "deprecated": {
-                return { deprecated: true };
-            }
-
-            case "externalDocs": {
-                return {
-                    externalDocs: {
-                        url: parsedResponse.name,
-                        description: parsedResponse.description,
-                    },
-                };
-            }
-
-            case "server": {
-                return {
-                    servers: [
-                        {
-                            url: parsedResponse.name,
-                            description: parsedResponse.description,
-                        },
-                    ],
-                };
-            }
-
-            case "tag": {
-                return { tags: [nameAndDescription] };
-            }
-
-            case "cookieParam":
-            case "headerParam":
-            case "queryParam":
-            case "pathParam": {
-                return {
-                    parameters: [
-                        {
-                            name: parsedResponse.name,
-                            in: tag.tag.replace(/Param$/, ""),
-                            description: parsedResponse.description,
-                            required: parsedResponse.required,
-                            schema: parsedResponse.schema,
-                        },
-                    ],
-                };
-            }
-
-            case "bodyContent": {
-                return {
-                    requestBody: {
-                        content: {
-                            [parsedResponse.name.replace("*\\/*", "*/*")]: {
-                                schema: parsedResponse.schema,
-                            },
-                        },
-                    },
-                };
-            }
-
-            case "bodyExample": {
-                const [contentType, example] = parsedResponse.name.split(".");
-                return {
-                    requestBody: {
-                        content: {
-                            [contentType]: {
-                                examples: {
-                                    [example]: {
-                                        $ref: `#/components/examples/${parsedResponse.rawType}`,
-                                    },
-                                },
-                            },
-                        },
-                    },
-                };
-            }
-
-            case "bodyDescription": {
-                return { requestBody: { description: nameAndDescription } };
-            }
-
-            case "bodyRequired": {
-                return { requestBody: { required: true } };
-            }
-
-            case "response": {
-                return {
-                    responses: {
-                        [parsedResponse.name]: {
-                            description: parsedResponse.description,
-                        },
-                    },
-                };
-            }
-
-            case "callback": {
-                return {
-                    callbacks: {
-                        [parsedResponse.name]: {
-                            $ref: `#/components/callbacks/${parsedResponse.rawType}`,
-                        },
-                    },
-                };
-            }
-
-            case "responseContent": {
-                const [status, contentType] = parsedResponse.name.split(".");
-
-                return {
-                    responses: {
-                        [status]: {
-                            content: {
-                                [contentType]: {
-                                    schema: parsedResponse.schema,
-                                },
-                            },
-                        },
-                    },
-                };
-            }
-
-            case "responseHeaderComponent": {
-                const [status, header] = parsedResponse.name.split(".");
-                return {
-                    responses: {
-                        [status]: {
-                            headers: {
-                                [header]: {
-                                    $ref: `#/components/headers/${parsedResponse.rawType}`,
-                                },
-                            },
-                        },
-                    },
-                };
-            }
-
-            case "responseHeader": {
-                const [status, header] = parsedResponse.name.split(".");
-                return {
-                    responses: {
-                        [status]: {
-                            headers: {
-                                [header]: {
-                                    description: parsedResponse.description,
-                                    schema: parsedResponse.schema,
-                                },
-                            },
-                        },
-                    },
-                };
-            }
-
-            case "responseExample": {
-                const [status, contentType, example] = parsedResponse.name.split(".");
-                return {
-                    responses: {
-                        [status]: {
-                            content: {
-                                [contentType]: {
-                                    examples: {
-                                        [example]: {
-                                            $ref: `#/components/examples/${parsedResponse.rawType}`,
-                                        },
-                                    },
-                                },
-                            },
-                        },
-                    },
-                };
-            }
-
-            case "responseLink": {
-                const [status, link] = parsedResponse.name.split(".");
-                return {
-                    responses: {
-                        [status]: {
-                            links: {
-                                [link]: {
-                                    $ref: `#/components/links/${parsedResponse.rawType}`,
-                                },
-                            },
-                        },
-                    },
-                };
-            }
-
-            case "bodyComponent": {
-                return {
-                    requestBody: {
-                        $ref: `#/components/requestBodies/${parsedResponse.rawType}`,
-                    },
-                };
-            }
-
-            case "responseComponent": {
-                return {
-                    responses: {
-                        [parsedResponse.name]: {
-                            $ref: `#/components/responses/${parsedResponse.rawType}`,
-                        },
-                    },
-                };
-            }
-
-            case "paramComponent": {
-                return {
-                    parameters: [{ $ref: `#/components/parameters/${parsedResponse.rawType}` }],
-                };
-            }
-
-            case "security": {
-                const [security, scopeItem] = parsedResponse.name.split(".");
-                let scope: string[] = [];
-                if (scopeItem) {
-                    scope = [scopeItem];
-                }
-                return {
-                    security: { [security]: scope },
-                };
-            }
-
-            default: {
-                return {};
-            }
-        }
-    });
-}
-
-const commentsToOpenApi = (fileContents: string, verbose?: boolean): { spec: OpenApiObject; loc: number }[] => {
-    const openAPIRegex = /^(GET|PUT|POST|DELETE|OPTIONS|HEAD|PATCH|TRACE) \/.*$/;
-
-    const jsDocumentComments = parseComments(fileContents, { spacing: "preserve" });
-
-    return jsDocumentComments
-        .filter((comment) => openAPIRegex.test(comment.description.trim()))
-        .map((comment) => {
-            // Line count, number of tags + 1 for description.
-            // - Don't count line-breaking due to long descriptions
-            // - Don't count empty lines
-            const loc = comment.tags.length + 1;
-
-            const result = mergeWith({}, ...tagsToObjects(comment.tags, verbose), customizer);
-
-            fixSecurityObject(result);
-
-            const [method, path]: string[] = comment.description.split(" ");
-
-            const pathsObject: PathsObject = {
-                [(path as string).trim()]: {
-                    [(method as string).toLowerCase().trim()]: {
-                        ...result,
-                    },
-                },
-            };
-
-            // Purge all undefined objects/arrays.
-            const spec = JSON.parse(JSON.stringify({ paths: pathsObject }));
-
-            return {
-                spec,
-                loc,
-            };
-        });
-};
-
-export default commentsToOpenApi;

package/src/options.ts

@@ -1,28 +0,0 @@
-const DEFAULT_OPTIONS = {
-    cwd: undefined,
-    extension: [".js", ".cjs", ".mjs", ".ts", ".tsx", ".jsx", ".yaml", ".yml"],
-    include: ["**"],
-    exclude: [
-        "coverage/**",
-        "packages/*/test{,s}/**",
-        "**/*.d.ts",
-        "test{,s}/**",
-        "test{,-*}.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}",
-        "**/*{.,-}test.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}",
-        "**/__tests__/**",
-
-        /* Exclude common development tool configuration files */
-        "**/{ava,babel,nyc}.config.{js,cjs,mjs}",
-        "**/jest.config.{js,cjs,mjs,ts}",
-        "**/{karma,rollup,webpack}.config.js",
-        "**/.{eslint,mocha}rc.{js,cjs}",
-        "**/.{travis,yarnrc}.yml",
-        "**/{docker-compose}.yml",
-
-        // always ignore '**/node_modules/**'
-    ],
-    excludeNodeModules: true,
-    verbose: true,
-};
-
-export default DEFAULT_OPTIONS;