next-openapi-gen 0.1.2 → 0.2.1

package/README.md

@@ -9,6 +9,7 @@
 
 ## Interfaces
 
+- Scalar
 - Swagger
 - Redoc
 - Stoplight Elements
@@ -19,7 +20,7 @@
 - **Automatic OpenAPI Generation**: Generate OpenAPI 3.0 documentation from your Next.js routes, automatically parsing TypeScript types for parameters, request bodies and responses. Field comments in TypeScript types are reflected as descriptions in the OpenAPI schema.
 - **Complex TypeScript Types**: Use complex TypeScript types, such as `nested objects`, `arrays`, `enums` and `unions` (mapped to anyOf). This enables a more comprehensive representation of data structures directly in the OpenAPI schema.
 - **JSDoc-Based Documentation**: Document API routes with optional JSDoc comments, including tags like `@openapi`, `@auth`, `@desc`, `@params`, `@body`, and `@response` to easily define route metadata.
-- **Multiple UI Interfaces**: Choose between `Swagger UI`, `Redoc`, `Stoplight Elements` or `RapiDoc` to visualize your API documentation. Customize the interface to fit your preferences.
+- **Multiple UI Interfaces**: Choose between `Scalar`, `Swagger UI`, `Redoc`, `Stoplight Elements` or `RapiDoc` to visualize your API documentation. Customize the interface to fit your preferences.
 - **Real-time Documentation**: As your API evolves, regenerate the OpenAPI documentation with a single command, ensuring your documentation is always up to date.
 - **Easy configuration**: Customize generator behavior using the `next.openapi.json` configuration file, allowing for quick adjustments without modifying the code.
 
@@ -33,20 +34,20 @@ yarn add next-openapi-gen
 
 ### Step 1: Initialize Configuration and Setup
 
-Run the following command to generate the `next.openapi.json` configuration file and automatically set up Swagger UI with `/api-docs` routes:
+Run the following command to generate the `next.openapi.json` configuration file and automatically set up Scalar UI with `/api-docs` routes:
 
 ```bash
-npx next-openapi-gen init --ui swagger --docs-url api-docs
+npx next-openapi-gen init --ui scalar --docs-url api-docs
 ```
 
 Parameters:
-- **ui**: `swagger` | `redoc` | `stoplight` | `rapidoc`
+- **ui**: `scalar` | `swagger` | `redoc` | `stoplight` | `rapidoc`
 - **docs-url**: url on which api docs will be visible
 
 This command does the following:
 
 - Generates a `next.openapi.json` file, which stores the OpenAPI configuration for your project.
-- Installs Swagger UI to provide an API documentation interface.
+- Installs Scalar UI to provide an API documentation interface.
 - Adds an `/api-docs` route in the Next.js app for visualizing the generated OpenAPI documentation.
 
 ### Step 2: Add JSDoc Comments to Your API Routes
@@ -57,7 +58,7 @@ Annotate your API routes using JSDoc comments. Here's an example:
   <table>
     <tr>
       <th>Login route</th>
-      <th>Swagger</th>
+      <th>Scalar / Swagger</th>
     </tr>
     <tr>
       <td>
@@ -87,13 +88,14 @@ Annotate your API routes using JSDoc comments. Here's an example:
   ```
   </td>
   <td>
-    <img width="340" alt="api-login" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-login.png" alt-text="api-login"/>
+    <img width="340" alt="api-login-scalar" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-login-scalar.png" alt-text="api-login"/>
+    <img width="340" alt="api-login-swagger" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-login-swagger.png" alt-text="api-login-swagger"/>
   </td>
   </tr>
 
   <tr>
       <th>Users route</th>
-      <th>Swagger</th>
+      <th>Scalar / Swagger</th>
     </tr>
   <tr>
       <td>
@@ -145,7 +147,8 @@ Annotate your API routes using JSDoc comments. Here's an example:
   ```
   </td>
   <td>
-    <img width="340" alt="api-users" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-users.png" alt-text="api-users"/>
+    <img width="340" alt="api-users-scalar" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-users-scalar.png" alt-text="api-users-scalar"/>
+    <img width="340" alt="api-users-swagger" src="https://raw.githubusercontent.com/tazo90/next-openapi-gen/refs/heads/main/assets/api-users-swagger.png" alt-text="api-users-swagger"/>
   </td>
   </tr>
 </table>
@@ -159,11 +162,11 @@ Run the following command to generate the OpenAPI schema based on your API route
 npx next-openapi-gen generate
 ```
 
-This command processes all your API routes, extracts the necessary information from JSDoc comments, and generates the OpenAPI schema, typically saved to a `swagger.json` file in the `public` folder.
+This command processes all your API routes, extracts the necessary information from JSDoc comments, and generates the OpenAPI schema, typically saved to a `openapi.json` file in the `public` folder.
 
 ### Step 4: View API Documentation
 
-With the `/api-docs` route generated from the init command, you can now access your API documentation through Swagger UI by navigating to `http://localhost:3000/api-docs`.
+With the `/api-docs` route generated from the init command, you can now access your API documentation through Scalar UI by navigating to `http://localhost:3000/api-docs`.
 
 ## JSDoc tags
 
@@ -181,8 +184,8 @@ The `next.openapi.json` file allows you to configure the behavior of the OpenAPI
 - **apiDir**: (default: `./src/app/api`) The directory where your API routes are stored.
 - **schemaDir**: (default: `./src`) The directory where your schema definitions are stored.
 - **docsUrl**: (default: `./api-docs`) Route where OpenAPI UI is available.
-- **ui**: (default: `swagger`) OpenAPI UI interface.
-- **outputFile**: (default: `./swagger.json`) The file where the generated OpenAPI specification will be saved in `public` folder.
+- **ui**: (default: `scalar`) OpenAPI UI interface.
+- **outputFile**: (default: `./openapi.json`) The file where the generated OpenAPI specification will be saved in `public` folder.
 - **includeOpenApiRoutes**: (default: `false`) When `true`, the generator will only include routes that have the `@openapi` tag in their JSDoc comments.
 
 ## Interface providers
@@ -190,7 +193,8 @@ The `next.openapi.json` file allows you to configure the behavior of the OpenAPI
 <div align="center">
 <table>
   <thead>
-   <th>SwaggerUI</th>
+   <th>Scalar</th>
+   <th>Swagger</th>
    <th>Redoc</th>
    <th>Stoplight Elements</th>
    <th>RapiDoc</th>

package/dist/commands/generate.js

@@ -1,21 +1,21 @@
-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 config = generator.getConfig();
-    // Create api dir if not exists
-    const apiDir = path.resolve(config.apiDir);
-    await fse.ensureDir(apiDir);
-    // Create public dir if not exists
-    const outputDir = path.resolve("./public");
-    await fse.ensureDir(outputDir);
-    const apiDocs = generator.generate();
-    // 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}`);
-}
+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 config = generator.getConfig();
+    // Create api dir if not exists
+    const apiDir = path.resolve(config.apiDir);
+    await fse.ensureDir(apiDir);
+    // Create public dir if not exists
+    const outputDir = path.resolve("./public");
+    await fse.ensureDir(outputDir);
+    const apiDocs = generator.generate();
+    // 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

@@ -1,104 +1,111 @@
-import path from "path";
-import fse from "fs-extra";
-import fs from "fs";
-import ora from "ora";
-import { exec } from "child_process";
-import util from "util";
-import openapiTemplate from "../openapi-template.js";
-import { swaggerDeps, SwaggerUI } from "../components/swagger.js";
-import { redocDeps, RedocUI } from "../components/redoc.js";
-import { stoplightDeps, StoplightUI } from "../components/stoplight.js";
-import { rapidocDeps, RapidocUI } from "../components/rapidoc.js";
-const execPromise = util.promisify(exec);
-const spinner = ora("Initializing project with OpenAPI template...\n");
-const getPackageManager = async () => {
-    let currentDir = process.cwd();
-    while (true) {
-        // Check for Yarn lock file
-        if (fs.existsSync(path.join(currentDir, "yarn.lock"))) {
-            return "yarn";
-        }
-        // Check for PNPM lock file
-        if (fs.existsSync(path.join(currentDir, "pnpm-lock.yaml"))) {
-            return "pnpm";
-        }
-        // If we're at the root directory, break the loop
-        const parentDir = path.dirname(currentDir);
-        if (parentDir === currentDir) {
-            break; // We've reached the root
-        }
-        currentDir = parentDir; // Move up one directory
-    }
-    // Default to npm if no lock files are found
-    return "npm";
-};
-function getDocsPage(ui, outputFile) {
-    let DocsComponent = SwaggerUI;
-    if (ui === "redoc") {
-        DocsComponent = RedocUI;
-    }
-    else if (ui === "stoplight") {
-        DocsComponent = StoplightUI;
-    }
-    else if (ui === "rapidoc") {
-        DocsComponent = RapidocUI;
-    }
-    return DocsComponent(outputFile);
-}
-function getDocsPageDependencies(ui) {
-    let deps = [];
-    if (ui === "swagger") {
-        deps = swaggerDeps;
-    }
-    else if (ui === "redoc") {
-        deps = redocDeps;
-    }
-    else if (ui === "stoplight") {
-        deps = stoplightDeps;
-    }
-    else if (ui === "rapidoc") {
-        deps = rapidocDeps;
-    }
-    return deps.join(" ");
-}
-async function createDocsPage(ui, outputFile) {
-    const paths = ["app", "api-docs"];
-    const srcPath = path.join(process.cwd(), "src");
-    if (fs.existsSync(srcPath)) {
-        paths.unshift("src");
-    }
-    const docsDir = path.join(process.cwd(), ...paths);
-    await fs.promises.mkdir(docsDir, { recursive: true });
-    const docsPage = getDocsPage(ui, outputFile);
-    const componentPath = path.join(docsDir, "page.tsx");
-    await fs.promises.writeFile(componentPath, docsPage.trim());
-    spinner.succeed(`Created ${paths.join("/")}/page.tsx for ${ui}.`);
-}
-async function installDependencies(ui) {
-    const packageManager = await getPackageManager();
-    const installCmd = `${packageManager} ${packageManager === "npm" ? "install" : "add"}`;
-    const deps = getDocsPageDependencies(ui);
-    spinner.succeed(`Installing ${deps} dependencies...`);
-    const resp = await execPromise(`${installCmd} ${deps}`);
-    spinner.succeed(`Successfully installed ${deps}.`);
-}
-function extendOpenApiTemplate(spec, options) {
-    spec.ui = options.ui ?? spec.ui;
-    spec.docsUrl = options.docsUrl ?? spec.docsUrl;
-}
-export async function init(options) {
-    const { ui, docsUrl } = options;
-    spinner.start();
-    try {
-        const outputPath = path.join(process.cwd(), "next.openapi.json");
-        const template = { ...openapiTemplate };
-        extendOpenApiTemplate(template, { docsUrl, ui });
-        await fse.writeJson(outputPath, template, { spaces: 2 });
-        spinner.succeed(`Created OpenAPI template in next.openapi.json`);
-        createDocsPage(ui, template.outputFile);
-        installDependencies(ui);
-    }
-    catch (error) {
-        spinner.fail(`Failed to initialize project: ${error.message}`);
-    }
-}
+import path from "path";
+import fse from "fs-extra";
+import fs from "fs";
+import ora from "ora";
+import { exec } from "child_process";
+import util from "util";
+import openapiTemplate from "../openapi-template.js";
+import { scalarDeps, ScalarUI } from "../components/scalar.js";
+import { swaggerDeps, SwaggerUI } from "../components/swagger.js";
+import { redocDeps, RedocUI } from "../components/redoc.js";
+import { stoplightDeps, StoplightUI } from "../components/stoplight.js";
+import { rapidocDeps, RapidocUI } from "../components/rapidoc.js";
+const execPromise = util.promisify(exec);
+const spinner = ora("Initializing project with OpenAPI template...\n");
+const getPackageManager = async () => {
+    let currentDir = process.cwd();
+    while (true) {
+        // Check for Yarn lock file
+        if (fs.existsSync(path.join(currentDir, "yarn.lock"))) {
+            return "yarn";
+        }
+        // Check for PNPM lock file
+        if (fs.existsSync(path.join(currentDir, "pnpm-lock.yaml"))) {
+            return "pnpm";
+        }
+        // If we're at the root directory, break the loop
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            break; // We've reached the root
+        }
+        currentDir = parentDir; // Move up one directory
+    }
+    // Default to npm if no lock files are found
+    return "npm";
+};
+function getDocsPage(ui, outputFile) {
+    let DocsComponent = ScalarUI;
+    if (ui === "swagger") {
+        DocsComponent = SwaggerUI;
+    }
+    else if (ui === "redoc") {
+        DocsComponent = RedocUI;
+    }
+    else if (ui === "stoplight") {
+        DocsComponent = StoplightUI;
+    }
+    else if (ui === "rapidoc") {
+        DocsComponent = RapidocUI;
+    }
+    return DocsComponent(outputFile);
+}
+function getDocsPageDependencies(ui) {
+    let deps = [];
+    if (ui === "scalar") {
+        deps = scalarDeps;
+    }
+    else if (ui === "swagger") {
+        deps = swaggerDeps;
+    }
+    else if (ui === "redoc") {
+        deps = redocDeps;
+    }
+    else if (ui === "stoplight") {
+        deps = stoplightDeps;
+    }
+    else if (ui === "rapidoc") {
+        deps = rapidocDeps;
+    }
+    return deps.join(" ");
+}
+async function createDocsPage(ui, outputFile) {
+    const paths = ["app", "api-docs"];
+    const srcPath = path.join(process.cwd(), "src");
+    if (fs.existsSync(srcPath)) {
+        paths.unshift("src");
+    }
+    const docsDir = path.join(process.cwd(), ...paths);
+    await fs.promises.mkdir(docsDir, { recursive: true });
+    const docsPage = getDocsPage(ui, outputFile);
+    const componentPath = path.join(docsDir, "page.tsx");
+    await fs.promises.writeFile(componentPath, docsPage.trim());
+    spinner.succeed(`Created ${paths.join("/")}/page.tsx for ${ui}.`);
+}
+async function installDependencies(ui) {
+    const packageManager = await getPackageManager();
+    const installCmd = `${packageManager} ${packageManager === "npm" ? "install" : "add"}`;
+    const deps = getDocsPageDependencies(ui);
+    spinner.succeed(`Installing ${deps} dependencies...`);
+    const resp = await execPromise(`${installCmd} ${deps}`);
+    spinner.succeed(`Successfully installed ${deps}.`);
+}
+function extendOpenApiTemplate(spec, options) {
+    spec.ui = options.ui ?? spec.ui;
+    spec.docsUrl = options.docsUrl ?? spec.docsUrl;
+}
+export async function init(options) {
+    const { ui, docsUrl } = options;
+    spinner.start();
+    try {
+        const outputPath = path.join(process.cwd(), "next.openapi.json");
+        const template = { ...openapiTemplate };
+        extendOpenApiTemplate(template, { docsUrl, ui });
+        await fse.writeJson(outputPath, template, { spaces: 2 });
+        spinner.succeed(`Created OpenAPI template in next.openapi.json`);
+        createDocsPage(ui, template.outputFile);
+        installDependencies(ui);
+    }
+    catch (error) {
+        spinner.fail(`Failed to initialize project: ${error.message}`);
+    }
+}

package/dist/components/rapidoc.js

@@ -1,5 +1,5 @@
-export const rapidocDeps = ["rapidoc"];
-export function RapidocUI(outputFile) {
+export const rapidocDeps = ["rapidoc"];
+export function RapidocUI(outputFile) {
     return `
 "use client";
 
@@ -16,5 +16,5 @@ export default function ApiDocsPage() {
     </section>
   );
 }
-`;
-}
+`;
+}

package/dist/components/redoc.js

@@ -1,5 +1,5 @@
-export const redocDeps = ["redoc"];
-export function RedocUI(outputFile) {
+export const redocDeps = ["redoc"];
+export function RedocUI(outputFile) {
     return `
 "use client";
 
@@ -12,5 +12,5 @@ export default async function ApiDocsPage() {
     </section>
   );
 }
-`;
-}
+`;
+}

package/dist/components/scalar.js

@@ -0,0 +1,20 @@
+export const scalarDeps = ["@scalar/api-reference-react", "ajv"];
+export function ScalarUI(outputFile) {
+    return `
+"use client";
+
+import { ApiReferenceReact } from "@scalar/api-reference-react";
+
+import "@scalar/api-reference-react/style.css";
+
+export default function ApiDocsPage() {
+  return (
+    <ApiReferenceReact
+      configuration={{
+        url: "/${outputFile}",
+      }}
+    />
+  );
+}
+`;
+}

package/dist/components/stoplight.js

@@ -1,5 +1,5 @@
-export const stoplightDeps = ["@stoplight/elements"];
-export function StoplightUI(outputFile) {
+export const stoplightDeps = ["@stoplight/elements"];
+export function StoplightUI(outputFile) {
     return `
 "use client";
 
@@ -13,5 +13,5 @@ export default function ApiDocsPage() {
     </section>
   );
 }
-`;
-}
+`;
+}

package/dist/components/swagger.js

@@ -1,9 +1,9 @@
-export const swaggerDeps = [
-    "swagger-ui",
-    "swagger-ui-react",
-    "--legacy-peer-deps", // @temp: swagger-ui-react does not support React 19 now.
-];
-export function SwaggerUI(outputFile) {
+export const swaggerDeps = [
+    "swagger-ui",
+    "swagger-ui-react",
+    "--legacy-peer-deps", // @temp: swagger-ui-react does not support React 19 now.
+];
+export function SwaggerUI(outputFile) {
     return `
 import "swagger-ui-react/swagger-ui.css";
 
@@ -21,5 +21,5 @@ export default async function ApiDocsPage() {
     </section>
   );
 }
-`;
-}
+`;
+}

package/dist/index.js

@@ -1,22 +1,22 @@
-#!/usr/bin/env node
-import { Command, Option } from "commander";
-import { init } from "./commands/init.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")
-    .addOption(new Option("-i, --ui <type>", "Specify the UI type, e.g., swagger")
-    .choices(["swagger", "redoc", "stoplight", "rapidoc"])
-    .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(generate);
-program.parse(process.argv);
+#!/usr/bin/env node
+import { Command, Option } from "commander";
+import { init } from "./commands/init.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")
+    .addOption(new Option("-i, --ui <type>", "Specify the UI type, e.g., scalar")
+    .choices(["scalar", "swagger", "redoc", "stoplight", "rapidoc"])
+    .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(generate);
+program.parse(process.argv);

package/dist/lib/openapi-generator.js

@@ -1,34 +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;
-    }
-}
+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;
+    }
+}