This generator automatically scans all your API endpoints in server/api/ and generates inline OpenAPI documentation using defineRouteMeta.

🚀 Features

• Automatic Endpoint Discovery: Scans all .ts files in server/api/ recursively
• Smart Schema Detection: Automatically detects Zod validation schemas used in .parse() calls
• Method Detection: Determines HTTP method from filename (.post.ts, .put.ts, etc.)
• Route Path Generation: Converts file paths to API routes (handles [id] parameters)
• Auth Detection: Identifies endpoints that require authentication
• Flexible Exclusion System: Exclude routes using regex patterns, exact matches, or file patterns
• Inline Documentation: Generates proper defineRouteMeta with OpenAPI spec that works with Nitro's build-time analysis

🎯 Problem Solved

This generator solves the Nitro OpenAPI limitation where imported constants and functions (like zodToOpenAPI(), commonResponses[]) are not resolved during build-time static analysis. Instead, it generates fully inline OpenAPI documentation that Nitro can process correctly.

🔧 Usage

Run the Generator

npm run openapi:generate

What It Does

1. Scans all API endpoints in server/api/
2. Detects validation schemas from imports and .parse() calls
3. Generates inline OpenAPI documentation for each endpoint
4. Adds defineRouteMeta with complete OpenAPI spec to each file

Example Output

For an endpoint like server/api/permissions/create.post.ts, it will add:

defineRouteMeta({
  openAPI: {
    summary: 'Create permissions',
    description: 'Create permissions with proper validation and error handling',
    tags: ['Permissions'],
    requestBody: {
      required: true,
      content: {
        'application/json': {
          schema: {
            type: 'object',
            properties: {
              name: { type: 'string', description: 'Permission name' },
              description: { type: 'string', description: 'Permission description' },
              resource: { type: 'string', description: 'Resource type' },
              action: { type: 'string', description: 'Action type' }
            }
          }
        }
      }
    },
    responses: {
      '200': {
        description: 'Permissions created successfully',
        content: {
          'application/json': {
            schema: {
              type: 'object',
              properties: {
                status: { type: 'string', example: 'success' },
                data: { type: 'object', description: 'Created/updated resource' }
              }
            }
          }
        }
      },
      '400': {
        description: 'Bad Request - Invalid input data',
        content: {
          'application/json': {
            schema: {
              type: 'object',
              properties: {
                statusCode: { type: 'number', example: 400 },
                statusMessage: { type: 'string', example: 'Bad Request' },
                message: { type: 'string', example: 'Validation error' },
                data: { type: 'object' }
              }
            }
          }
        }
      },
      '401': {
        description: 'Unauthorized',
        content: {
          'application/json': {
            schema: {
              type: 'object',
              properties: {
                statusCode: { type: 'number', example: 401 },
                statusMessage: { type: 'string', example: 'Unauthorized' },
                message: { type: 'string', example: 'Authentication required' }
              }
            }
          }
        }
      },
      '500': {
        description: 'Internal Server Error',
        content: {
          'application/json': {
            schema: {
              type: 'object',
              properties: {
                statusCode: { type: 'number', example: 500 },
                statusMessage: { type: 'string', example: 'Internal Server Error' },
                message: { type: 'string', example: 'An unexpected error occurred' }
              }
            }
          }
        }
      }
    }
  }
})

🔍 Detection Logic

Schema Detection

• Looks for imports from files containing schema or schemas
• Detects validation schemas used in .parse() calls
• Identifies schemas with names containing: create, update, add, assign, remove, change

Response Schema Inference

• Automatically detects response schemas by name pattern (*ResponseSchema)
• Generates appropriate success/error responses based on HTTP method

Authentication Detection

• Detects auth usage by looking for:
  • auth.api.getSession
  • getAuthenticatedUser
  • session?.user

Smart Property Generation

The generator intelligently creates schema properties based on schema names:

• User schemas: name, email, password (for create)
• Role schemas: name, description
• Permission schemas: name, description, resource, action
• Organization schemas: name, description, slug

⚙️ Configuration

Basic Configuration

The generator is designed to work out-of-the-box with your current project structure. Key settings:

• Server Directory: server/api
• File Pattern: *.ts (excludes README files)
• Skip Condition: Files already containing defineRouteMeta with openAPI

Exclusion Configuration

Customize which endpoints to exclude by editing scripts/openapi-config.ts:

export const openApiConfig: GeneratorConfig = {
  // Regex patterns to exclude routes
  excludePatterns: [
    '/auth/.*',              // Exclude all auth routes
    '/admin/.*',             // Exclude all admin routes  
    '.*\\.test\\..*',        // Exclude test files
  ],

  // Exact route matches to exclude (use {param} format)
  excludeRoutes: [
    '/auth/{...all}',        // Exclude catch-all auth route
    '/health',               // Exclude health check
  ],

  // File path patterns to exclude
  excludeFiles: [
    'middleware',            // Exclude files with 'middleware' in path
    '.test.',                // Exclude test files
  ]
}

Important Notes:

• Use {param} format for route exclusions, not [param]
• Regex patterns are tested against both route paths and file paths
• File patterns use simple string matching

🔄 Re-running

The generator is safe to re-run. It will:

• ✅ Skip files that already have OpenAPI documentation
• ✅ Add documentation to new endpoints
• ✅ Preserve existing manual documentation

🎉 Benefits

1. No More Manual Maintenance: Documentation stays in sync automatically
2. Nitro Compatible: Works with build-time static analysis
3. Type Safety: Leverages your existing Zod schemas
4. Flexible Exclusion: Skip auth, admin, test, or any other routes easily
5. Consistent Format: Standardized documentation across all endpoints
6. Error Handling: Comprehensive error response documentation

🔧 Troubleshooting

Generator Not Finding Schemas

• Ensure schema files are in directories containing schema or schemas
• Check that validation schemas follow naming convention (*Schema)
• Verify .parse() calls are using the expected pattern

Documentation Not Appearing

• Check that Nitro's OpenAPI generation is enabled
• Verify the generated defineRouteMeta syntax is correct
• Ensure no syntax errors in the generated code

Missing Properties

• The generator uses intelligent property inference
• Add custom patterns to generateSchemaProperties() method if needed
• Consider manual documentation for complex schemas