// src/app/api/products/[id]/route.ts import { NextRequest, NextResponse } from "next/server"; import { z } from "zod"; export const ProductParams = z.object({ id: z.string().describe("Product 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"), }); /**  * Get product information  * @description Fetches detailed product information by ID  * @pathParams ProductParams  * @response ProductResponse  * @openapi  */ export async function GET( request: NextRequest, { params }: { params: { id: string } } ) { // Implementation... }

// src/app/api/users/[id]/route.ts import { NextRequest, NextResponse } from "next/server"; type UserParams = { id: string; // User ID }; type UserResponse = { id: string; // User ID name: string; // Full name email: string; // Email address }; /**  * Get user information  * @description Fetches detailed user information by ID  * @pathParams UserParams  * @response UserResponse  * @openapi  */ export async function GET( request: NextRequest, { params }: { params: { id: string } } ) { // Implementation... }

// src/db/schema.ts - Define your Drizzle table import { pgTable, serial, varchar, text } from "drizzle-orm/pg-core"; export const posts = pgTable("posts", { id: serial("id").primaryKey(), title: varchar("title", { length: 255 }).notNull(), content: text("content").notNull(), }); // src/schemas/post.ts - Generate Zod schema with drizzle-zod import { createInsertSchema, createSelectSchema } from "drizzle-zod"; import { posts } from "@/db/schema"; export const CreatePostSchema = createInsertSchema(posts, { title: (schema) => schema.title.min(5).max(255).describe("Post title"), content: (schema) => schema.content.min(10).describe("Post content"), }); export const PostResponseSchema = createSelectSchema(posts); // src/app/api/posts/route.ts - Use in your API route /**  * Create a new post  * @description Create a new blog post with Drizzle-Zod validation  * @body CreatePostSchema  * @response 201:PostResponseSchema  * @openapi  */ export async function POST(request: NextRequest) { const body = await request.json(); const validated = CreatePostSchema.parse(body); // Implementation... }

// src/app/api/users/[id]/route.ts // Zod const UserParams = z.object({ id: z.string().describe("User ID"), }); // Or TypeScript type UserParams = { id: string; // User ID }; /**  * @pathParams UserParams  */ export async function GET() { // ... }

// src/app/api/users/route.ts // 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  */ export async function GET() { // ... }

// src/app/api/users/route.ts // 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  */ export async function POST() { // ... }

// src/app/api/users/route.ts // Zod const UserResponse = z.object({ id: z.string().describe("User ID"), name: z.string().describe("Full name"), email: z.string().email().describe("Email address"), 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  */ export async function GET() { // ... } // Alternative formats with inline description /**  * @response UserResponse:Returns user profile data  */ export async function GET() { // ... } /**  * @response 201:UserResponse:Returns newly created user  */ export async function POST() { // ... } /**  * @response 204:Empty:User successfully deleted  */ export async function DELETE() { // ... }

// src/app/api/protected/route.ts /**  * @auth bearer  */ export async function GET() { // ... }

// src/app/api/v1/route.ts // 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; /** @deprecated Use firstName and lastName instead */ fullName?: string; email: string; }; /**  * @body UserSchema  * @response UserResponse  */ export async function GET() { // ... }

// src/app/api/users/[id]/route.ts /**  * Get user by ID  * @operationId getUserById  * @pathParams UserParams  * @response UserResponse  */ export async function GET() { // ... } // Generates: operationId: "getUserById" instead of auto-generated "get-users-{id}"

// src/app/api/upload/route.ts // 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  */ export async function POST() { // ... }

/**  * Auto-default responses  * @response UserResponse  * @openapi  */ export async function GET() {} // Generates: 200:UserResponse + common errors (400, 401, 500) /**  * With custom description inline  * @response UserResponse:Complete user profile information  * @openapi  */ export async function GET() {} // Generates: 200:UserResponse (with custom description) + common errors /**  * Override response set  * @response ProductResponse  * @responseSet public  * @openapi  */ export async function GET() {} // Generates: 200:ProductResponse + public errors (400, 500) /**  * Add custom responses with description  * @response 201:UserResponse:User created successfully  * @add 409:ConflictResponse  * @openapi  */ export async function POST() {} // Generates: 201:UserResponse (with custom description) + common errors + 409:ConflictResponse /**  * Combine multiple sets  * @response UserResponse  * @responseSet auth,crud  * @add 429:RateLimitResponse  * @openapi  */ export async function PUT() {} // Combines: auth + crud errors + custom 429

// src/app/api/internal/route.ts /**  * Internal route - not for documentation  * @ignore  */ export async function GET() { // This route will not appear in OpenAPI documentation }

// src/app/api/users/[id]/posts/[postId]/route.ts // Will automatically detect 'id' and 'postId' parameters export async function GET() { // ... }

// src/app/api/llms/route.ts import { NextResponse } from "next/server"; // Define generic response wrapper type MyApiSuccessResponseBody<T> = T & { success: true; httpCode: string; }; // Define specific response data type LLMSResponse = { llms: Array<{ id: string; name: string; provider: string; isDefault: boolean; }>; }; /**  * Get list of available LLMs  * @description Get list of available LLMs with success wrapper  * @response 200:MyApiSuccessResponseBody<LLMSResponse>  * @openapi  */ export async function GET() { return NextResponse.json({ success: true, httpCode: "200", llms: [ { id: "gpt-5", name: "GPT-5", provider: "OpenAI", isDefault: true, }, ], }); }

// Zod validation chains are properly converted to OpenAPI schemas const EmailSchema = z .string() .email() .min(5) .max(100) .describe("Email address"); // Converts to OpenAPI with email format, minLength and maxLength

// You can use TypeScript with Zod types import { z } from "zod"; const UserSchema = z.object({ id: z.string().uuid(), name: z.string().min(2), }); // Use z.infer to create a TypeScript type type User = z.infer<typeof UserSchema>; // The library will be able to recognize this schema by reference `UserSchema` or `User` type.

// Define reusable schema factory export function createPaginatedSchema<T extends z.ZodTypeAny>(dataSchema: T) { return z.object({ data: z.array(dataSchema).describe("Array of items"), pagination: z.object({ nextCursor: z.string().nullable(), hasMore: z.boolean(), limit: z.number().int().positive(), }), }); } // Use in your schemas - automatically expanded in OpenAPI export const PaginatedUsersSchema = createPaginatedSchema(UserSchema); export const PaginatedProductsSchema = createPaginatedSchema(ProductSchema);

import { createInsertSchema } from "drizzle-zod"; import { posts } from "@/db/schema"; export const CreatePostSchema = createInsertSchema(posts, { title: (schema) => schema.title.min(5).max(255), content: (schema) => schema.content.min(10), published: (schema) => schema.published.optional(), });