next-openapi-gen 0.0.3 → 0.0.6

package/dist/commands/generate.js

@@ -0,0 +1,18 @@
+import fs from "fs";
+import fse from "fs-extra";
+import path from "path";
+import ora from "ora";
+import { OpenApiGenerator } from "../lib/openapi-generator.js";
+export async function generate() {
+    const spinner = ora("Generating OpenAPI specification...\n").start();
+    const generator = new OpenApiGenerator();
+    const apiDocs = generator.generate();
+    const config = generator.getConfig();
+    // Check if public dir exists
+    const outputDir = path.resolve("./public");
+    await fse.ensureDir(outputDir);
+    // Write api docs
+    const outputFile = path.join(outputDir, config.outputFile);
+    fs.writeFileSync(outputFile, JSON.stringify(apiDocs, null, 2));
+    spinner.succeed(`OpenAPI specification generated at ${outputFile}`);
+}

package/dist/commands/init.js

@@ -4,27 +4,9 @@ import fs from "fs";
 import ora from "ora";
 import { exec } from "child_process";
 import util from "util";
+import openapiTemplate from "../openapi-template.js";
 const execPromise = util.promisify(exec);
 const spinner = ora("Initializing project with OpenAPI template...\n");
-const openApiTemplate = {
-    openapi: "3.0.0",
-    info: {
-        title: "API Documentation",
-        version: "1.0.0",
-        description: "This is the OpenAPI specification for your project.",
-    },
-    servers: [
-        {
-            url: "http://localhost:3000",
-            description: "Local development server",
-        },
-    ],
-    paths: {},
-    apiPath: "./src/app/api",
-    docsUrl: "api-docs",
-    ui: "swagger",
-    outputPath: "./public/swagger.json",
-};
 const getPackageManager = async () => {
     if (fs.existsSync(path.join(process.cwd(), "yarn.lock"))) {
         return "yarn";
@@ -75,12 +57,14 @@ function extendOpenApiTemplate(spec, options) {
     spec.ui = options.ui ?? spec.ui;
     spec.docsUrl = options.docsUrl ?? spec.docsUrl;
 }
-export async function init(ui, docsUrl) {
+export async function init(options) {
+    const { ui, docsUrl } = options;
     spinner.start();
     try {
         const outputPath = path.join(process.cwd(), "next.openapi.json");
-        extendOpenApiTemplate(openApiTemplate, { docsUrl, ui });
-        await fse.writeJson(outputPath, openApiTemplate, { spaces: 2 });
+        const template = { ...openapiTemplate };
+        extendOpenApiTemplate(template, { docsUrl, ui });
+        await fse.writeJson(outputPath, template, { spaces: 2 });
         spinner.succeed(`Created OpenAPI template in next.openapi.json`);
         if (ui === "swagger") {
             createDocsPage();

package/dist/index.js

@@ -1,18 +1,22 @@
 #!/usr/bin/env node
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { init } from "./commands/init.js";
-import { generateOpenapiSpec } from "./commands/generate-openapi-spec.js";
+import { generate } from "./commands/generate.js";
 const program = new Command();
 program
     .name("next-openapi-gen")
     .version("0.0.1")
     .description("Super fast and easy way to generate OpenAPI documentation for Next.js");
 program
-    .command("init <ui> <docs-url>")
+    .command("init")
+    .addOption(new Option("-i, --ui <type>", "Specify the UI type, e.g., swagger")
+    .choices(["swagger", "element", "redoc"])
+    .default("swagger"))
+    .option("-u, --docs-url <url>", "Specify the docs URL", "api-docs")
     .description("Initialize a openapi specification")
     .action(init);
 program
     .command("generate")
     .description("Generate a specification based on api routes")
-    .action(generateOpenapiSpec);
+    .action(generate);
 program.parse(process.argv);

package/dist/lib/openapi-generator.js

@@ -0,0 +1,34 @@
+import path from "path";
+import fs from "fs";
+import { RouteProcessor } from "./route-processor.js";
+import { cleanSpec } from "./utils.js";
+export class OpenApiGenerator {
+    config;
+    template;
+    routeProcessor;
+    constructor() {
+        const templatePath = path.resolve("./next.openapi.json");
+        this.template = JSON.parse(fs.readFileSync(templatePath, "utf-8"));
+        this.config = this.getConfig();
+        this.routeProcessor = new RouteProcessor(this.config);
+    }
+    getConfig() {
+        // @ts-ignore
+        const { apiDir, schemaDir, docsUrl, ui, outputFile, includeOpenApiRoutes } = this.template;
+        return {
+            apiDir,
+            schemaDir,
+            docsUrl,
+            ui,
+            outputFile,
+            includeOpenApiRoutes,
+        };
+    }
+    generate() {
+        const { apiDir } = this.config;
+        this.routeProcessor.scanApiRoutes(apiDir);
+        this.template.paths = this.routeProcessor.getSwaggerPaths();
+        const openapiSpec = cleanSpec(this.template);
+        return openapiSpec;
+    }
+}

package/dist/lib/route-processor.js

@@ -0,0 +1,135 @@
+import * as t from "@babel/types";
+import fs from "fs";
+import path from "path";
+import traverse from "@babel/traverse";
+import { parse } from "@babel/parser";
+import { SchemaProcessor } from "./schema-processor.js";
+import { capitalize, extractJSDocComments, getOperationId } from "./utils.js";
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+const MUTATION_HTTP_METHODS = ["PATCH", "POST", "PUT"];
+export class RouteProcessor {
+    swaggerPaths = {};
+    schemaProcessor;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.schemaProcessor = new SchemaProcessor(config.schemaDir);
+    }
+    isRoute(varName) {
+        return HTTP_METHODS.includes(varName);
+    }
+    processFile(filePath) {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const ast = parse(content, {
+            sourceType: "module",
+            plugins: ["typescript"],
+        });
+        traverse.default(ast, {
+            ExportNamedDeclaration: (path) => {
+                const declaration = path.node.declaration;
+                if (t.isFunctionDeclaration(declaration) &&
+                    t.isIdentifier(declaration.id)) {
+                    const dataTypes = extractJSDocComments(path);
+                    if (this.isRoute(declaration.id.name)) {
+                        this.addRouteToPaths(declaration.id.name, filePath, dataTypes);
+                    }
+                }
+                if (t.isVariableDeclaration(declaration)) {
+                    declaration.declarations.forEach((decl) => {
+                        if (t.isVariableDeclarator(decl) && t.isIdentifier(decl.id)) {
+                            if (this.isRoute(decl.id.name)) {
+                                this.addRouteToPaths(decl.id.name, filePath, extractJSDocComments(path));
+                            }
+                        }
+                    });
+                }
+            },
+        });
+    }
+    scanApiRoutes(dir) {
+        const files = fs.readdirSync(dir);
+        files.forEach((file) => {
+            const filePath = path.join(dir, file);
+            const stat = fs.statSync(filePath);
+            if (stat.isDirectory()) {
+                this.scanApiRoutes(filePath);
+                // @ts-ignore
+            }
+            else if (file.endsWith(".ts")) {
+                this.processFile(filePath);
+            }
+        });
+    }
+    addRouteToPaths(varName, filePath, dataTypes) {
+        const method = varName.toLowerCase();
+        const routePath = this.getRoutePath(filePath);
+        const rootPath = capitalize(routePath.split("/")[1]);
+        const operationId = getOperationId(routePath, method);
+        const { summary, description, isOpenApi } = dataTypes;
+        if (this.config.includeOpenApiRoutes && !isOpenApi) {
+            // If flag is enabled and there is no @openapi tag, then skip path
+            return;
+        }
+        if (!this.swaggerPaths[routePath]) {
+            this.swaggerPaths[routePath] = {};
+        }
+        const { params, body, responses } = this.schemaProcessor.getSchemaContent(dataTypes);
+        const definition = {
+            operationId: operationId,
+            summary: summary,
+            description: description,
+            tags: [rootPath],
+            parameters: params,
+        };
+        // Add request body
+        if (MUTATION_HTTP_METHODS.includes(method.toUpperCase())) {
+            definition.requestBody =
+                this.schemaProcessor.createRequestBodySchema(body);
+        }
+        // Add responses
+        definition.responses = responses
+            ? this.schemaProcessor.createResponseSchema(responses)
+            : {};
+        this.swaggerPaths[routePath][method] = definition;
+    }
+    getRoutePath(filePath) {
+        const suffixPath = filePath.split("api")[1];
+        return suffixPath
+            .replace("route.ts", "")
+            .replaceAll("\\", "/")
+            .replace(/\/$/, "");
+    }
+    getSortedPaths(paths) {
+        function comparePaths(a, b) {
+            const aMethods = this.swaggerPaths[a] || {};
+            const bMethods = this.swaggerPaths[b] || {};
+            // Extract tags for all methods in path a
+            const aTags = Object.values(aMethods).flatMap((method) => method.tags || []);
+            // Extract tags for all methods in path b
+            const bTags = Object.values(bMethods).flatMap((method) => method.tags || []);
+            // Assume we are interested in only the first tags
+            const aPrimaryTag = aTags[0] || "";
+            const bPrimaryTag = bTags[0] || "";
+            // Sort alphabetically based on the first tag
+            const tagComparison = aPrimaryTag.localeCompare(bPrimaryTag);
+            if (tagComparison !== 0) {
+                return tagComparison; // Return the result of tag comparison
+            }
+            // Compare lengths of the paths
+            const aLength = a.split("/").length;
+            const bLength = b.split("/").length;
+            // Return the result of length comparison
+            return aLength - bLength; // Shorter paths come before longer ones
+        }
+        return Object.keys(paths)
+            .sort(comparePaths.bind(this))
+            .reduce((sorted, key) => {
+            sorted[key] = paths[key];
+            return sorted;
+        }, {});
+    }
+    getSwaggerPaths() {
+        const paths = this.getSortedPaths(this.swaggerPaths);
+        return this.getSortedPaths(paths);
+    }
+}

package/dist/lib/schema-processor.js

@@ -0,0 +1,155 @@
+import fs from "fs";
+import path from "path";
+import { parse } from "@babel/parser";
+import traverse from "@babel/traverse";
+import * as t from "@babel/types";
+export class SchemaProcessor {
+    schemaDir;
+    constructor(schemaDir) {
+        this.schemaDir = path.resolve(schemaDir);
+    }
+    findSchemaDefinition(schemaName) {
+        let schemaNode = null;
+        this.scanSchemaDir(this.schemaDir, schemaName, (node) => {
+            schemaNode = node;
+        });
+        return schemaNode;
+    }
+    scanSchemaDir(dir, schemaName, callback) {
+        const files = fs.readdirSync(dir);
+        files.forEach((file) => {
+            const filePath = path.join(dir, file);
+            const stat = fs.statSync(filePath);
+            if (stat.isDirectory()) {
+                this.scanSchemaDir(filePath, schemaName, callback);
+            }
+            else if (file.endsWith(".ts")) {
+                this.processSchemaFile(filePath, schemaName, callback);
+            }
+        });
+    }
+    processSchemaFile(filePath, schemaName, callback) {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const ast = parse(content, {
+            sourceType: "module",
+            plugins: ["typescript"],
+        });
+        traverse.default(ast, {
+            VariableDeclarator: (path) => {
+                if (t.isIdentifier(path.node.id, { name: schemaName })) {
+                    callback(path.node.init || path.node);
+                }
+            },
+            TSTypeAliasDeclaration: (path) => {
+                if (t.isIdentifier(path.node.id, { name: schemaName })) {
+                    callback(path.node.typeAnnotation);
+                }
+            },
+            TSInterfaceDeclaration: (path) => {
+                if (t.isIdentifier(path.node.id, { name: schemaName })) {
+                    callback(path.node);
+                }
+            },
+        });
+    }
+    extractTypesFromSchema(schema, dataType) {
+        const result = dataType === "params" ? [] : {};
+        const handleProperty = (property) => {
+            const key = property.key.name;
+            const typeAnnotation = property.typeAnnotation?.typeAnnotation?.type;
+            const type = this.getTypeFromAnnotation(typeAnnotation);
+            const isOptional = !!property.optional; // check if property is optional
+            let description = "";
+            // get comments for field
+            if (property.trailingComments && property.trailingComments.length) {
+                description = property.trailingComments[0].value.trim(); // get first comment
+            }
+            const field = {
+                type: type,
+                description: description,
+            };
+            if (dataType === "params") {
+                // @ts-ignore
+                result.push({
+                    name: key,
+                    in: "query",
+                    schema: field,
+                    required: !isOptional,
+                });
+            }
+            else {
+                result[key] = field;
+            }
+        };
+        if (schema.body?.body) {
+            schema.body.body.forEach(handleProperty);
+        }
+        if (schema.type === "TSTypeLiteral" && schema.members) {
+            schema.members.forEach(handleProperty);
+        }
+        return result;
+    }
+    getTypeFromAnnotation(type) {
+        switch (type) {
+            case "TSStringKeyword":
+                return "string";
+            case "TSNumberKeyword":
+                return "number";
+            case "TSBooleanKeyword":
+                return "boolean";
+            // Add other cases as needed.
+            default:
+                return "object"; // fallback to object for unknown types
+        }
+    }
+    createRequestBodySchema(body) {
+        return {
+            content: {
+                "application/json": {
+                    schema: {
+                        type: "object",
+                        properties: body,
+                    },
+                },
+            },
+        };
+    }
+    createResponseSchema(responses) {
+        return {
+            200: {
+                description: "Successful response",
+                content: {
+                    "application/json": {
+                        schema: {
+                            type: "object",
+                            properties: responses,
+                        },
+                    },
+                },
+            },
+        };
+    }
+    getSchemaContent({ paramsType, bodyType, responseType }) {
+        const paramsSchema = paramsType
+            ? this.findSchemaDefinition(paramsType)
+            : null;
+        const bodySchema = bodyType ? this.findSchemaDefinition(bodyType) : null;
+        const responseSchema = responseType
+            ? this.findSchemaDefinition(responseType)
+            : null;
+        let params = paramsSchema
+            ? this.extractTypesFromSchema(paramsSchema, "params")
+            : [];
+        let body = bodySchema
+            ? this.extractTypesFromSchema(bodySchema, "body")
+            : {};
+        let responses = responseSchema
+            ? this.extractTypesFromSchema(responseSchema, "responses")
+            : {};
+        return {
+            params,
+            body,
+            responses,
+        };
+    }
+}

package/dist/lib/utils.js

@@ -0,0 +1,66 @@
+export function capitalize(string) {
+    return string.charAt(0).toUpperCase() + string.slice(1);
+}
+export function extractJSDocComments(path) {
+    const comments = path.node.leadingComments;
+    let summary = "";
+    let description = "";
+    let paramsType = "";
+    let bodyType = "";
+    let responseType = "";
+    let isOpenApi = false;
+    if (comments) {
+        comments.forEach((comment) => {
+            const commentValue = cleanComment(comment.value);
+            isOpenApi = commentValue.includes("@openapi");
+            if (!summary) {
+                const summaryIndex = isOpenApi ? 1 : 0;
+                summary = commentValue.split("\n")[summaryIndex];
+            }
+            if (commentValue.includes("@desc")) {
+                const regex = /@desc:\s*(.*)/;
+                description = commentValue.match(regex)[1].trim();
+            }
+            if (commentValue.includes("@params")) {
+                paramsType = extractTypeFromComment(commentValue, "@params");
+            }
+            if (commentValue.includes("@body")) {
+                bodyType = extractTypeFromComment(commentValue, "@body");
+            }
+            if (commentValue.includes("@response")) {
+                responseType = extractTypeFromComment(commentValue, "@response");
+            }
+        });
+    }
+    return {
+        summary,
+        description,
+        paramsType,
+        bodyType,
+        responseType,
+        isOpenApi,
+    };
+}
+export function extractTypeFromComment(commentValue, tag) {
+    return commentValue.match(new RegExp(`${tag}\\s*:\\s*(\\w+)`))?.[1] || "";
+}
+export function cleanComment(commentValue) {
+    return commentValue.replace(/\*\s*/g, "").trim();
+}
+export function cleanSpec(spec) {
+    const propsToRemove = [
+        "apiDir",
+        "schemaDir",
+        "docsUrl",
+        "ui",
+        "outputFile",
+        "includeOpenApiRoutes",
+    ];
+    const newSpec = { ...spec };
+    propsToRemove.forEach((key) => delete newSpec[key]);
+    return newSpec;
+}
+export function getOperationId(routePath, method) {
+    const operation = routePath.replaceAll(/\//g, "-").replace(/^-/, "");
+    return `${method}-${operation}`;
+}

package/dist/openapi-template.js

@@ -0,0 +1,20 @@
+export default {
+    openapi: "3.0.0",
+    info: {
+        title: "API Documentation",
+        version: "1.0.0",
+        description: "This is the OpenAPI specification for your project.",
+    },
+    servers: [
+        {
+            url: "http://localhost:3000",
+            description: "Local development server",
+        },
+    ],
+    paths: {},
+    apiPath: "./src/app/api",
+    docsUrl: "api-docs",
+    ui: "swagger",
+    outputPath: "./public/swagger.json",
+    includeOpenApiRoutes: true,
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "description": "Automatically generate OpenAPI documentation for Next.js API",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "typings": "dist/index.d.ts",
   "bin": {
-    "next-openapi-gen": "./dist/index"
+    "next-openapi-gen": "./dist/index.js"
   },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "prepare": "npm run build"

package/dist/commands/generate-openapi-spec.js

@@ -1,168 +0,0 @@
-import { parse } from "@babel/parser";
-import traverse from "@babel/traverse";
-import * as t from "@babel/types";
-import fs from "fs";
-import path from "path";
-import ora from "ora";
-const apiDir = path.resolve("./src/app/api");
-const schemaDir = path.resolve("./src/types/schemas");
-const swaggerPaths = {};
-function extractSchemaFromZod(schemaNode) {
-    const properties = {};
-    schemaNode.arguments.forEach((arg) => {
-        if (t.isObjectExpression(arg)) {
-            arg.properties.forEach((prop) => {
-                if (t.isObjectProperty(prop) && t.isIdentifier(prop.key)) {
-                    // @ts-ignore
-                    const type = prop.value.callee.property.name;
-                    properties[prop.key.name] = { type };
-                }
-            });
-        }
-    });
-    return { type: "object", properties };
-}
-function findSchemaDefinition(schemaName) {
-    let schemaNode = null;
-    function processSchemaFile(filePath) {
-        const content = fs.readFileSync(filePath, "utf-8");
-        const ast = parse(content, {
-            sourceType: "module",
-            plugins: ["typescript"],
-        });
-        traverse.default(ast, {
-            VariableDeclarator(path) {
-                if (t.isIdentifier(path.node.id, { name: schemaName })) {
-                    if (t.isCallExpression(path.node.init)) {
-                        schemaNode = path.node.init;
-                    }
-                }
-            },
-        });
-    }
-    function scanSchemaDir(dir) {
-        const files = fs.readdirSync(dir);
-        files.forEach((file) => {
-            const filePath = path.join(dir, file);
-            const stat = fs.statSync(filePath);
-            if (stat.isDirectory()) {
-                scanSchemaDir(filePath);
-            }
-            else if (file.endsWith(".ts")) {
-                processSchemaFile(filePath);
-            }
-        });
-    }
-    scanSchemaDir(schemaDir);
-    return schemaNode;
-}
-function processFile(filePath) {
-    const content = fs.readFileSync(filePath, "utf-8");
-    const ast = parse(content, { sourceType: "module", plugins: ["typescript"] });
-    traverse.default(ast, {
-        ExportNamedDeclaration(path) {
-            const declaration = path.node.declaration;
-            if (t.isVariableDeclaration(declaration)) {
-                declaration.declarations.forEach((decl) => {
-                    if (t.isVariableDeclarator(decl) && t.isIdentifier(decl.id)) {
-                        const varName = decl.id.name;
-                        let schema = {};
-                        let options = {};
-                        if (varName === "POST" ||
-                            varName === "GET" ||
-                            varName === "PUT" ||
-                            varName === "PATCH" ||
-                            varName === "DELETE") {
-                            const handler = decl.init;
-                            // Handle schema definition
-                            if (fs.existsSync(schemaDir) &&
-                                t.isCallExpression(handler) &&
-                                t.isIdentifier(handler.callee, { name: "withAPI" })) {
-                                const [schemaIdentifier] = handler.arguments;
-                                if (t.isIdentifier(schemaIdentifier)) {
-                                    const schemaNode = findSchemaDefinition(schemaIdentifier.name);
-                                    const optionsNode = schemaNode.arguments[0];
-                                    if (schemaNode) {
-                                        // @TODO: add z.array tracking
-                                        if (t.isObjectExpression(optionsNode)) {
-                                            schema = extractSchemaFromZod(schemaNode);
-                                            options = optionsNode.properties.reduce((acc, prop) => {
-                                                if (t.isObjectProperty(prop) &&
-                                                    t.isIdentifier(prop.key)) {
-                                                    // @ts-ignore
-                                                    acc[prop.key.name] = prop.value.callee.property.name;
-                                                }
-                                                return acc;
-                                            }, {});
-                                        }
-                                    }
-                                }
-                            }
-                            const method = varName.toLowerCase();
-                            const routePath = filePath
-                                .replace(apiDir, "")
-                                .replace("route.ts", "")
-                                .replaceAll("\\", "/")
-                                .replace(/\/$/, "");
-                            const rootPath = routePath.split("/")[1];
-                            if (!swaggerPaths[routePath]) {
-                                swaggerPaths[routePath] = {};
-                            }
-                            swaggerPaths[routePath][method] = {
-                                operationId: options.opId,
-                                description: options.desc,
-                                tags: [rootPath],
-                                requestBody: {
-                                    content: {
-                                        "application/json": {
-                                            schema,
-                                        },
-                                    },
-                                },
-                                responses: {
-                                    200: {
-                                        description: "Successful response",
-                                        content: {
-                                            "application/json": {
-                                                schema: options.res,
-                                            },
-                                        },
-                                    },
-                                    400: {
-                                        description: "Validation error",
-                                    },
-                                    500: {
-                                        description: "Server error",
-                                    },
-                                },
-                            };
-                        }
-                    }
-                });
-            }
-        },
-    });
-}
-function scanDir(dir) {
-    const files = fs.readdirSync(dir);
-    files.forEach((file) => {
-        const filePath = path.join(dir, file);
-        const stat = fs.statSync(filePath);
-        if (stat.isDirectory()) {
-            scanDir(filePath);
-        }
-        else if (file.endsWith(".ts")) {
-            processFile(filePath);
-        }
-    });
-}
-export async function generateOpenapiSpec() {
-    const spinner = ora("Generating openapi specification...\n").start();
-    scanDir(apiDir);
-    const openapiPath = path.resolve("./next.openapi.json");
-    const openapiSpec = JSON.parse(fs.readFileSync(openapiPath, "utf-8"));
-    openapiSpec.paths = swaggerPaths;
-    const outputPath = path.resolve(openapiSpec.outputPath);
-    fs.writeFileSync(outputPath, JSON.stringify(openapiSpec, null, 2));
-    spinner.succeed(`Swagger spec generated at ${outputPath}`);
-}