next-openapi-gen 0.6.7 → 0.6.8

package/README.md

@@ -1,13 +1,13 @@
 # next-openapi-gen
 
-Automatically generate OpenAPI 3.0 documentation from Next.js projects, with support for TypeScript types and Zod schemas.
+Automatically generate OpenAPI 3.0 documentation from Next.js projects, with support for Zod schemas and TypeScript types.
 
 ## Features
 
 - ✅ Automatic OpenAPI documentation generation from Next.js code
 - ✅ Support for Next.js App Router (including `/api/users/[id]/route.ts` routes)
-- ✅ TypeScript types support
 - ✅ Zod schemas support
+- ✅ TypeScript types support
 - ✅ JSDoc comments support
 - ✅ Multiple UI interfaces: `Scalar`, `Swagger`, `Redoc`, `Stoplight` and `Rapidoc` available at `/api-docs` url
 - ✅ Path parameters detection (`/users/{id}`)
@@ -32,7 +32,7 @@ npm install next-openapi-gen --save-dev
 
 ```bash
 # Initialize OpenAPI configuration
-npx next-openapi-gen init --ui scalar --docs-url api-docs
+npx next-openapi-gen init --ui scalar --docs-url api-docs --schema zod
 
 # Generate OpenAPI documentation
 npx next-openapi-gen generate
@@ -58,7 +58,7 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
   ],
   "apiDir": "src/app/api",
   "schemaDir": "src/types", // or "src/schemas" for Zod schemas
-  "schemaType": "typescript", // or "zod" for Zod schemas
+  "schemaType": "zod", // or "typescript" for TypeScript types
   "outputFile": "openapi.json",
   "docsUrl": "/api-docs",
   "includeOpenApiRoutes": false,
@@ -72,7 +72,7 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
 | ---------------------- | ------------------------------------------------ |
 | `apiDir`               | Path to the API directory                        |
 | `schemaDir`            | Path to the types/schemas directory              |
-| `schemaType`           | Schema type: `"typescript"` or `"zod"`           |
+| `schemaType`           | Schema type: `"zod"` or `"typescript"`           |
 | `outputFile`           | Path to the OpenAPI output file                  |
 | `docsUrl`              | API documentation URL (for Swagger UI)           |
 | `includeOpenApiRoutes` | Whether to include only routes with @openapi tag |
@@ -83,28 +83,29 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
 
 ## Documenting Your API
 
-### With TypeScript Types
+### With Zod Schemas
 
 ```typescript
-// src/app/api/users/[id]/route.ts
+// src/app/api/products/[id]/route.ts
 
 import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
 
-type UserParams = {
-  id: string; // User ID
-};
+export const ProductParams = z.object({
+  id: z.string().describe("Product ID"),
+});
 
-type UserResponse = {
-  id: string; // User ID
-  name: string; // Full name
-  email: string; // Email address
-};
+export const ProductResponse = z.object({
+  id: z.string().describe("Product ID"),
+  name: z.string().describe("Product name"),
+  price: z.number().positive().describe("Product price"),
+});
 
 /**
- * Get user information
- * @description Fetches detailed user information by ID
- * @pathParams UserParams
- * @response UserResponse
+ * Get product information
+ * @description Fetches detailed product information by ID
+ * @pathParams ProductParams
+ * @response ProductResponse
  * @openapi
  */
 export async function GET(
@@ -115,29 +116,28 @@ export async function GET(
 }
 ```
 
-### With Zod Schemas
+### With TypeScript Types
 
 ```typescript
-// src/app/api/products/[id]/route.ts
+// src/app/api/users/[id]/route.ts
 
 import { NextRequest, NextResponse } from "next/server";
-import { z } from "zod";
 
-export const ProductParams = z.object({
-  id: z.string().describe("Product ID"),
-});
+type UserParams = {
+  id: string; // User ID
+};
 
-export const ProductResponse = z.object({
-  id: z.string().describe("Product ID"),
-  name: z.string().describe("Product name"),
-  price: z.number().positive().describe("Product price"),
-});
+type UserResponse = {
+  id: string; // User ID
+  name: string; // Full name
+  email: string; // Email address
+};
 
 /**
- * Get product information
- * @description Fetches detailed product information by ID
- * @pathParams ProductParams
- * @response ProductResponse
+ * Get user information
+ * @description Fetches detailed user information by ID
+ * @pathParams UserParams
+ * @response UserResponse
  * @openapi
  */
 export async function GET(
@@ -178,8 +178,9 @@ npx next-openapi-gen init
 This command will generate following elements:
 
 - Generate `next.openapi.json` configuration file
-- Install UI interface (default `Scalar`)
+- Set up `Scalar` UI for documentation display
 - Add `/api-docs` page to display OpenAPI documentation
+- Configure `zod` as the default schema tool
 
 ### 2. Generate Documentation
 
@@ -192,7 +193,7 @@ This command will generate OpenAPI documentation based on your API code:
 - Scan API directories for routes
 - Analyze types/schemas
 - Generate OpenAPI file (`openapi.json`) in `public` folder
-- Create Swagger/Scalar UI endpoint and page (if enabled)
+- Create Scalar/Swagger UI endpoint and page (if enabled)
 
 ### 3. View API Documentation
 
@@ -205,16 +206,16 @@ To see API documenation go to `http://localhost:3000/api-docs`
 ```typescript
 // src/app/api/users/[id]/route.ts
 
-// TypeScript
-type UserParams = {
-  id: string; // User ID
-};
-
-// Or Zod
+// Zod
 const UserParams = z.object({
   id: z.string().describe("User ID"),
 });
 
+// Or TypeScript
+type UserParams = {
+  id: string; // User ID
+};
+
 /**
  * @pathParams UserParams
  */
@@ -228,20 +229,20 @@ export async function GET() {
 ```typescript
 // src/app/api/users/route.ts
 
-// TypeScript
-type UsersQueryParams = {
-  page?: number; // Page number
-  limit?: number; // Results per page
-  search?: string; // Search phrase
-};
-
-// Or Zod
+// Zod
 const UsersQueryParams = z.object({
   page: z.number().optional().describe("Page number"),
   limit: z.number().optional().describe("Results per page"),
   search: z.string().optional().describe("Search phrase"),
 });
 
+// Or TypeScript
+type UsersQueryParams = {
+  page?: number; // Page number
+  limit?: number; // Results per page
+  search?: string; // Search phrase
+};
+
 /**
  * @params UsersQueryParams
  */
@@ -255,20 +256,20 @@ export async function GET() {
 ```typescript
 // src/app/api/users/route.ts
 
-// TypeScript
-type CreateUserBody = {
-  name: string; // Full name
-  email: string; // Email address
-  password: string; // Password
-};
-
-// Or Zod
+// Zod
 const CreateUserBody = z.object({
   name: z.string().describe("Full name"),
   email: z.string().email().describe("Email address"),
   password: z.string().min(8).describe("Password"),
 });
 
+// Or TypeScript
+type CreateUserBody = {
+  name: string; // Full name
+  email: string; // Email address
+  password: string; // Password
+};
+
 /**
  * @body CreateUserBody
  * @bodyDescription User registration data including email and password
@@ -283,15 +284,7 @@ export async function POST() {
 ```typescript
 // src/app/api/users/route.ts
 
-// TypeScript
-type UserResponse = {
-  id: string; // User ID
-  name: string; // Full name
-  email: string; // Email address
-  createdAt: Date; // Creation date
-};
-
-// Or Zod
+// Zod
 const UserResponse = z.object({
   id: z.string().describe("User ID"),
   name: z.string().describe("Full name"),
@@ -299,6 +292,14 @@ const UserResponse = z.object({
   createdAt: z.date().describe("Creation date"),
 });
 
+// Or TypeScript
+type UserResponse = {
+  id: string; // User ID
+  name: string; // Full name
+  email: string; // Email address
+  createdAt: Date; // Creation date
+};
+
 /**
  * @response UserResponse
  * @responseDescription Returns newly created user object
@@ -326,7 +327,15 @@ export async function GET() {
 ```typescript
 // src/app/api/v1/route.ts
 
-// TypeScript
+// Zod
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  fullName: z.string().optional().describe("@deprecated Use name instead"),
+  email: z.string().email(),
+});
+
+// Or TypeScript
 type UserResponse = {
   id: string;
   name: string;
@@ -335,14 +344,6 @@ type UserResponse = {
   email: string;
 };
 
-// Or Zod
-const UserSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  fullName: z.string().optional().describe("@deprecated Use name instead"),
-  email: z.string().email(),
-});
-
 /**
  * @body UserSchema
  * @response UserResponse
@@ -357,20 +358,20 @@ export async function GET() {
 ```typescript
 // src/app/api/upload/route.ts
 
-// TypeScript
-type FileUploadFormData = {
-  file: File;
-  description?: string;
-  category: string;
-};
-
-// Or Zod
+// Zod
 const FileUploadSchema = z.object({
   file: z.custom<File>().describe("Image file (PNG/JPG)"),
   description: z.string().optional().describe("File description"),
   category: z.string().describe("File category"),
 });
 
+// Or TypeScript
+type FileUploadFormData = {
+  file: File;
+  description?: string;
+  category: string;
+};
+
 /**
  * @body FileUploadSchema
  * @contentType multipart/form-data

package/dist/commands/init.js

@@ -92,14 +92,15 @@ async function installDependencies(ui) {
 function extendOpenApiTemplate(spec, options) {
     spec.ui = options.ui ?? spec.ui;
     spec.docsUrl = options.docsUrl ?? spec.docsUrl;
+    spec.schemaType = options.schemaType ?? spec.schemaType;
 }
 export async function init(options) {
-    const { ui, docsUrl } = options;
+    const { ui, docsUrl, schemaType } = options;
     spinner.start();
     try {
         const outputPath = path.join(process.cwd(), "next.openapi.json");
         const template = { ...openapiTemplate };
-        extendOpenApiTemplate(template, { docsUrl, ui });
+        extendOpenApiTemplate(template, { docsUrl, ui, schemaType });
         await fse.writeJson(outputPath, template, { spaces: 2 });
         spinner.succeed(`Created OpenAPI template in next.openapi.json`);
         createDocsPage(ui, template.outputFile);

package/dist/components/rapidoc.js

@@ -1,20 +1,20 @@
 export const rapidocDeps = ["rapidoc"];
 export function RapidocUI(outputFile) {
-    return `
-"use client";
-
-import "rapidoc";
-
-export default function ApiDocsPage() {
-  return (
-    <section style={{ height: "100vh" }}>
-      <rapi-doc
-        spec-url="${outputFile}"
-        render-style="read"
-        style={{ height: "100vh", width: "100%" }}
-      ></rapi-doc>
-    </section>
-  );
-}
+    return `
+"use client";
+
+import "rapidoc";
+
+export default function ApiDocsPage() {
+  return (
+    <section style={{ height: "100vh" }}>
+      <rapi-doc
+        spec-url="${outputFile}"
+        render-style="read"
+        style={{ height: "100vh", width: "100%" }}
+      ></rapi-doc>
+    </section>
+  );
+}
 `;
 }

package/dist/components/redoc.js

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

package/dist/components/stoplight.js

@@ -1,17 +1,17 @@
 export const stoplightDeps = ["@stoplight/elements"];
 export function StoplightUI(outputFile) {
-    return `
-"use client";
-
-import { API } from "@stoplight/elements";
-import "@stoplight/elements/styles.min.css";
-
-export default function ApiDocsPage() {
-  return (
-    <section style={{ height: "100vh" }}>
-      <API apiDescriptionUrl="${outputFile}" />
-    </section>
-  );
-}
+    return `
+"use client";
+
+import { API } from "@stoplight/elements";
+import "@stoplight/elements/styles.min.css";
+
+export default function ApiDocsPage() {
+  return (
+    <section style={{ height: "100vh" }}>
+      <API apiDescriptionUrl="${outputFile}" />
+    </section>
+  );
+}
 `;
 }

package/dist/index.js

@@ -5,7 +5,7 @@ import { generate } from "./commands/generate.js";
 const program = new Command();
 program
     .name("next-openapi-gen")
-    .version("0.0.1")
+    .version("0.6.7")
     .description("Super fast and easy way to generate OpenAPI documentation for Next.js");
 program
     .command("init")
@@ -13,6 +13,7 @@ program
     .choices(["scalar", "swagger", "redoc", "stoplight", "rapidoc"])
     .default("swagger"))
     .option("-u, --docs-url <url>", "Specify the docs URL", "api-docs")
+    .option("-s, --schema <schemaType>", "Specify the schema type", "zod")
     .description("Initialize a openapi specification")
     .action(init);
 program

package/dist/openapi-template.js

@@ -65,7 +65,7 @@ export default {
     },
     apiDir: "./src/app/api",
     schemaDir: "./src",
-    schemaType: "typescript",
+    schemaType: "zod",
     docsUrl: "api-docs",
     ui: "scalar",
     outputFile: "openapi.json",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.6.7",
-  "description": "Automatically generate OpenAPI 3.0 documentation from Next.js projects, with support for TypeScript types and Zod schemas.",
+  "version": "0.6.8",
+  "description": "Automatically generate OpenAPI 3.0 documentation from Next.js projects, with support for Zod schemas and TypeScript types.",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.mjs",