nextjs-auto-swagger-gen 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 auto-swagger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# auto-swagger
+
+> Zero-config, code-first API documentation generator for Next.js and Node.js
+
+[![npm version](https://badge.fury.io/js/auto-swagger.svg)](https://www.npmjs.com/package/auto-swagger)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Write APIs normally. Docs generate themselves.**
+
+- ❌ NO manual Swagger files
+- ❌ NO decorators everywhere  
+- ❌ NO YAML/JSON configs
+- ❌ NO schema duplication
+- ✅ Code is the source of truth
+- ✅ TypeScript-first
+- ✅ Zero or near-zero config
+
+## Installation
+
+```bash
+# Using npm
+npm install auto-swagger
+
+# Using yarn
+yarn add auto-swagger
+
+# Using pnpm
+pnpm add auto-swagger
+```
+
+## Quick Start
+
+### Option 1: CLI (Recommended for production builds)
+
+```bash
+# Initialize config (optional)
+npx auto-swagger init
+
+# Generate documentation
+npx auto-swagger generate
+
+# Start documentation server
+npx auto-swagger serve
+```
+
+### Option 2: Runtime (Development mode)
+
+```typescript
+// app/api-docs/route.ts
+import { createDocsHandler } from 'auto-swagger';
+
+export const { GET } = createDocsHandler();
+```
+
+That's it! Visit `/api-docs` to see your documentation.
+
+## How It Works
+
+auto-swagger automatically:
+
+1. **Scans** your project for API route files
+2. **Parses** TypeScript AST to understand your code
+3. **Infers** request/response schemas from types
+4. **Generates** OpenAPI 3.1 specification
+5. **Serves** interactive Swagger UI
+
+### Supported Patterns
+
+#### Next.js App Router
+
+```
+app/
+├── api/
+│   ├── users/
+│   │   ├── route.ts          → /api/users
+│   │   └── [id]/
+│   │       └── route.ts      → /api/users/{id}
+│   └── posts/
+│       └── route.ts          → /api/posts
+```
+
+#### Next.js Pages Router
+
+```
+pages/
+└── api/
+    ├── users/
+    │   ├── index.ts          → /api/users
+    │   └── [id].ts           → /api/users/{id}
+    └── posts.ts              → /api/posts
+```
+
+## API Patterns
+
+### Basic Route Handler
+
+```typescript
+// app/api/users/route.ts
+
+export async function GET(request: Request) {
+  const users = await db.users.findMany();
+  return Response.json(users);
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const user = await db.users.create(body);
+  return Response.json(user, { status: 201 });
+}
+```
+
+### With TypeScript Types
+
+```typescript
+// Types are automatically inferred
+interface CreateUserInput {
+  email: string;
+  name: string;
+  role: 'admin' | 'user';
+}
+
+export async function POST(request: Request) {
+  const body = await request.json() as CreateUserInput;
+  // auto-swagger infers the request body schema
+  return Response.json({ success: true });
+}
+```
+
+### With Zod Schemas
+
+```typescript
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+  role: z.enum(['admin', 'user']),
+});
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const validated = CreateUserSchema.parse(body);
+  // auto-swagger converts Zod schema to OpenAPI
+  return Response.json(validated);
+}
+```
+
+### Comment-Based Hints
+
+```typescript
+/**
+ * Get all users
+ * Returns a paginated list of users
+ * 
+ * @tags users
+ * @auth bearer
+ * @rate-limit 100/min
+ */
+export async function GET(request: Request) {
+  // ...
+}
+
+/**
+ * Delete a user
+ * @deprecated Use soft delete instead
+ */
+export async function DELETE(request: Request, { params }) {
+  // ...
+}
+```
+
+## Configuration
+
+Create `auto-swagger.config.js` in your project root:
+
+```javascript
+/** @type {import('auto-swagger').AutoSwaggerConfig} */
+module.exports = {
+  // Scanner options
+  scanner: {
+    // Auto-detect framework (nextjs-app, nextjs-pages, express)
+    framework: 'auto',
+    
+    // Custom include patterns
+    include: ['**/app/**/route.ts'],
+    
+    // Exclude patterns
+    exclude: ['**/*.test.ts'],
+  },
+  
+  // OpenAPI specification options
+  openapi: {
+    title: 'My API',
+    version: '1.0.0',
+    description: 'API documentation',
+    
+    servers: [
+      { url: 'http://localhost:3000', description: 'Development' },
+      { url: 'https://api.example.com', description: 'Production' },
+    ],
+    
+    // Output format
+    outputFormat: 'both', // 'json' | 'yaml' | 'both'
+    outputPath: './docs',
+  },
+  
+  // UI options
+  ui: {
+    enabled: true,
+    path: '/api-docs',
+    theme: 'auto', // 'light' | 'dark' | 'auto'
+  },
+};
+```
+
+## CLI Commands
+
+### `auto-swagger init`
+
+Initialize configuration file.
+
+```bash
+npx auto-swagger init
+npx auto-swagger init --force  # Overwrite existing
+```
+
+### `auto-swagger generate`
+
+Generate OpenAPI specification and UI.
+
+```bash
+npx auto-swagger generate
+npx auto-swagger generate --output ./docs
+npx auto-swagger generate --json        # Only JSON
+npx auto-swagger generate --yaml        # Only YAML
+npx auto-swagger generate --no-ui       # Skip UI
+npx auto-swagger generate --verbose     # Show details
+```
+
+### `auto-swagger scan`
+
+Scan and display detected routes.
+
+```bash
+npx auto-swagger scan
+npx auto-swagger scan --json  # Output as JSON
+```
+
+### `auto-swagger serve`
+
+Start a documentation server.
+
+```bash
+npx auto-swagger serve
+npx auto-swagger serve --port 3001
+```
+
+## Programmatic API
+
+```typescript
+import { generate, detectRoutes, generateOpenAPISpec } from 'auto-swagger';
+
+// Simple generation
+const result = await generate({
+  rootDir: process.cwd(),
+  output: './docs',
+});
+
+console.log(result.spec);  // OpenAPI spec object
+console.log(result.json);  // JSON string
+console.log(result.yaml);  // YAML string
+console.log(result.html);  // Swagger UI HTML
+
+// Advanced usage
+const scanResult = await detectRoutes({
+  config: {
+    rootDir: process.cwd(),
+    framework: 'auto',
+  },
+});
+
+const spec = generateOpenAPISpec({
+  config: {
+    title: 'My API',
+    version: '1.0.0',
+  },
+  scanResult,
+});
+```
+
+## Type Inference
+
+auto-swagger infers types from multiple sources:
+
+### Priority Order
+
+1. **Zod schemas** - Highest fidelity, converts to JSON Schema
+2. **TypeScript types** - Type assertions and annotations
+3. **Code analysis** - Response.json() calls, status codes
+4. **Smart defaults** - Based on naming conventions
+
+### What's Inferred
+
+| Pattern | Inferred As |
+|---------|-------------|
+| `await req.json() as Type` | Request body schema |
+| `Response.json(data)` | Response schema |
+| `{ status: 201 }` | Response status code |
+| `[id]` in path | Path parameter |
+| `@auth bearer` comment | Security requirement |
+| `@deprecated` comment | Deprecated flag |
+| `@tags name` comment | Operation tags |
+
+## Supported Comment Hints
+
+| Hint | Description | Example |
+|------|-------------|---------|
+| `@tags` | Operation tags | `@tags users, admin` |
+| `@auth` | Auth requirement | `@auth bearer` |
+| `@deprecated` | Mark as deprecated | `@deprecated` |
+| `@summary` | Short description | `@summary Get all users` |
+| `@description` | Long description | `@description Returns...` |
+| `@rate-limit` | Rate limit info | `@rate-limit 100/min` |
+
+## Limitations
+
+### Current Limitations
+
+- Express/Fastify support is planned but not yet available
+- Complex TypeScript generics may not be fully resolved
+- Runtime-only type information (like Prisma types) requires hints
+- Dynamic routes with complex patterns need manual hints
+
+### Best Practices
+
+1. **Use Zod** for complex schemas - gives best inference
+2. **Add type assertions** - helps TypeScript inference
+3. **Write JSDoc comments** - provides descriptions
+4. **Keep routes focused** - one resource per route file
+
+## Examples
+
+See the [example](./example) directory for a complete Next.js application demonstrating all features.
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guide before submitting PRs.
+
+## License
+
+MIT © auto-swagger

package/dist/cli/index.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node