@engjts/nexus 0.1.0

package/src/advanced/swagger/createSwagger.ts

@@ -0,0 +1,12 @@
+import { SwaggerGenerator } from './SwaggerGenerator';
+import { SwaggerConfig } from './types';
+
+/**
+ * Create swagger instance (legacy)
+ * @deprecated Use swagger() plugin instead
+ */
+
+
+export function createSwagger(config: SwaggerConfig = {}): SwaggerGenerator {
+  return new SwaggerGenerator(config);
+}

package/src/advanced/swagger/generateOperationId.ts

@@ -0,0 +1,21 @@
+import { capitalize } from './capitalize';
+import { HTTPMethod } from '../../core/types';
+
+/**
+ * Generate operation ID from method and path
+ */
+
+
+export function generateOperationId(method: HTTPMethod, path: string): string {
+  const parts = path
+    .split('/')
+    .filter(Boolean)
+    .map(part => {
+      if (part.startsWith(':')) {
+        return 'By' + capitalize(part.slice(1));
+      }
+      return capitalize(part);
+    });
+
+  return method.toLowerCase() + parts.join('');
+}

package/src/advanced/swagger/generateSpec.ts

@@ -0,0 +1,105 @@
+import { buildOperation } from './buildOperation';
+import { convertPath } from './convertPath';
+import { StoredRoute, OpenAPISchema, SwaggerConfig, OpenAPISpec, OpenAPIOperation } from './types';
+
+// ============================================
+// SPEC GENERATION
+// ============================================
+/**
+ * Generate OpenAPI specification from routes
+ */
+
+
+export function generateSpec(
+  routes: StoredRoute[],
+  schemas: Map<string, OpenAPISchema>,
+  config: SwaggerConfig,
+  serverUrl: string
+): OpenAPISpec {
+  const paths: Record<string, Record<string, OpenAPIOperation>> = {};
+  const tags = new Map<string, { name: string; description?: string; }>();
+
+  // Add predefined tags
+  if (config.tags) {
+    config.tags.forEach(tag => tags.set(tag.name, tag));
+  }
+
+  for (const route of routes) {
+    // Skip swagger's own endpoints
+    if (route.path === config.path || route.path === config.specPath) {
+      continue;
+    }
+
+    // Skip untagged routes if configured
+    if (config.hideUntagged && (!route.meta?.tags || route.meta.tags.length === 0)) {
+      continue;
+    }
+
+    const openApiPath = convertPath(route.path);
+
+    if (!paths[openApiPath]) {
+      paths[openApiPath] = {};
+    }
+
+    const operation = buildOperation(route, config);
+    paths[openApiPath][route.method.toLowerCase()] = operation;
+
+    // Collect tags
+    if (route.meta?.tags) {
+      route.meta.tags.forEach(tag => {
+        if (!tags.has(tag)) {
+          tags.set(tag, { name: tag });
+        }
+      });
+    }
+  }
+
+  // Sort tags if configured
+  let tagList = Array.from(tags.values());
+  if (config.sortTags) {
+    tagList = tagList.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  const spec: OpenAPISpec = {
+    openapi: '3.0.3',
+    info: {
+      title: config.info?.title || 'API Documentation',
+      version: config.info?.version || '1.0.0',
+      ...config.info
+    },
+    paths,
+    tags: tagList
+  };
+
+  // Add servers
+  if (config.servers && config.servers.length > 0) {
+    spec.servers = config.servers;
+  } else if (serverUrl) {
+    spec.servers = [{ url: serverUrl, description: 'Current server' }];
+  }
+
+  // Add components
+  if (schemas.size > 0 || config.securitySchemes) {
+    spec.components = {};
+
+    if (schemas.size > 0) {
+      spec.components.schemas = Object.fromEntries(schemas);
+    }
+
+    if (config.securitySchemes) {
+      spec.components.securitySchemes = config.securitySchemes;
+    }
+  }
+
+  // Add global security
+  if (config.security) {
+    spec.security = config.security;
+  }
+
+  // Add external docs
+  if (config.externalDocs) {
+    spec.externalDocs = config.externalDocs;
+  }
+
+  return spec;
+}

package/src/advanced/swagger/generateSummary.ts

@@ -0,0 +1,24 @@
+import { HTTPMethod } from '../../core/types';
+
+/**
+ * Auto-generate summary from method and path
+ */
+
+
+export function generateSummary(method: HTTPMethod, path: string): string {
+  const parts = path.split('/').filter(Boolean);
+  const resource = parts.find(p => !p.startsWith(':')) || 'resource';
+  const hasId = parts.some(p => p.startsWith(':'));
+
+  const actions: Record<HTTPMethod, string> = {
+    'GET': hasId ? `Get ${resource} by ID` : `List all ${resource}`,
+    'POST': `Create ${resource}`,
+    'PUT': `Update ${resource}`,
+    'PATCH': `Partial update ${resource}`,
+    'DELETE': `Delete ${resource}`,
+    'HEAD': `Check ${resource}`,
+    'OPTIONS': `Options for ${resource}`
+  };
+
+  return actions[method] || `${method} ${path}`;
+}

package/src/advanced/swagger/generateSwaggerUI.ts

@@ -0,0 +1,70 @@
+import { generateThemeCss } from './generateThemeCss';
+import { SwaggerConfig } from './types';
+
+/**
+ * Generate Swagger UI HTML
+ */
+
+
+export function generateSwaggerUI(config: SwaggerConfig): string {
+  const specUrl = config.specPath || '/openapi.json';
+  const title = config.info?.title || 'API Documentation';
+  const themeCss = generateThemeCss(config.theme);
+  const customCss = config.customCss || '';
+  const favicon = config.favicon || 'https://unpkg.com/swagger-ui-dist@5/favicon-32x32.png';
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${title}</title>
+    <link rel="icon" type="image/png" href="${favicon}">
+    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+    <style>
+        html { box-sizing: border-box; overflow-y: scroll; }
+        *, *:before, *:after { box-sizing: inherit; }
+        body { margin: 0; background: #fafafa; }
+        .swagger-ui .topbar { padding: 10px 0; }
+        .swagger-ui .info { margin: 30px 0; }
+        .swagger-ui .info hgroup.main { margin: 0 0 20px 0; }
+        .swagger-ui .info .title { font-size: 36px; }
+        ${themeCss}
+        ${customCss}
+    </style>
+</head>
+<body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+    <script>
+        window.onload = function() {
+            window.ui = SwaggerUIBundle({
+                url: "${specUrl}",
+                dom_id: '#swagger-ui',
+                deepLinking: true,
+                docExpansion: '${config.docExpansion || 'list'}',
+                filter: ${config.filter !== false},
+                tryItOutEnabled: ${config.tryItOutEnabled !== false},
+                persistAuthorization: ${config.persistAuthorization !== false},
+                presets: [
+                    SwaggerUIBundle.presets.apis,
+                    SwaggerUIStandalonePreset
+                ],
+                plugins: [
+                    SwaggerUIBundle.plugins.DownloadUrl
+                ],
+                layout: "StandaloneLayout",
+                validatorUrl: null,
+                supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch', 'head', 'options'],
+                defaultModelsExpandDepth: 2,
+                defaultModelExpandDepth: 2,
+                displayRequestDuration: true,
+                showExtensions: true,
+                showCommonExtensions: true
+            });
+        };
+    </script>
+</body>
+</html>`;
+}

package/src/advanced/swagger/generateThemeCss.ts

@@ -0,0 +1,53 @@
+import { SwaggerTheme } from './types';
+
+// ============================================
+// SWAGGER UI GENERATION
+// ============================================
+/**
+ * Generate theme CSS
+ */
+export function generateThemeCss(theme?: 'light' | 'dark' | SwaggerTheme): string {
+  if (!theme) return '';
+
+  if (theme === 'dark') {
+    return `
+            body { background-color: #1a1a2e !important; }
+            .swagger-ui { background-color: #1a1a2e; }
+            .swagger-ui .topbar { background-color: #16213e; }
+            .swagger-ui .info .title { color: #e94560; }
+            .swagger-ui .scheme-container { background: #16213e; }
+            .swagger-ui .opblock-tag { color: #fff; border-bottom-color: #333; }
+            .swagger-ui .opblock { background: rgba(255,255,255,0.05); border-color: #333; }
+            .swagger-ui .opblock-summary { border-color: #333; }
+            .swagger-ui .opblock .opblock-summary-description { color: #aaa; }
+            .swagger-ui .opblock-body { background: #16213e; }
+            .swagger-ui .parameter__name, .swagger-ui .parameter__type { color: #fff; }
+            .swagger-ui table thead tr th { color: #fff; border-color: #333; }
+            .swagger-ui table tbody tr td { color: #ddd; border-color: #333; }
+            .swagger-ui .response-col_status { color: #e94560; }
+            .swagger-ui section.models { border-color: #333; }
+            .swagger-ui section.models h4 { color: #fff; }
+            .swagger-ui .model-box { background: #16213e; }
+            .swagger-ui .model { color: #ddd; }
+            .swagger-ui input[type=text], .swagger-ui textarea { 
+                background: #0f3460; color: #fff; border-color: #333; 
+            }
+            .swagger-ui select { background: #0f3460; color: #fff; }
+            .swagger-ui .btn { border-color: #e94560; }
+            .swagger-ui .btn.execute { background: #e94560; }
+        `;
+  }
+
+  if (typeof theme === 'object') {
+    return `
+            ${theme.backgroundColor ? `body { background-color: ${theme.backgroundColor} !important; }` : ''}
+            ${theme.primaryColor ? `.swagger-ui .info .title { color: ${theme.primaryColor}; }` : ''}
+            ${theme.primaryColor ? `.swagger-ui .btn.execute { background: ${theme.primaryColor}; border-color: ${theme.primaryColor}; }` : ''}
+            ${theme.headerColor ? `.swagger-ui .topbar { background-color: ${theme.headerColor}; }` : ''}
+            ${theme.textColor ? `.swagger-ui { color: ${theme.textColor}; }` : ''}
+            ${theme.fontFamily ? `.swagger-ui { font-family: ${theme.fontFamily}; }` : ''}
+        `;
+  }
+
+  return '';
+}

package/src/advanced/swagger/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Swagger/OpenAPI Integration for Nexus Framework
+ * Smart auto-detection of routes with zero configuration
+ * 
+ * @example
+ * ```typescript
+ * import { createApp, swagger } from 'nexus';
+ * 
+ * const app = createApp();
+ * 
+ * // Zero config - just works!
+ * app.feature(swagger());
+ * 
+ * // With config
+ * app.feature(swagger({
+ *   path: '/docs',
+ *   info: { title: 'My API', version: '1.0.0' }
+ * }));
+ * ```
+ */
+
+import { swagger } from './swagger';
+
+// Default export
+export default swagger;

package/src/advanced/swagger/swagger.ts

@@ -0,0 +1,237 @@
+import { generateSwaggerUI } from './generateSwaggerUI';
+import { generateSpec } from './generateSpec';
+import { Application } from '../../core/application';
+import { RouteConfig, HTTPMethod, Context, SchemaConfig, RouteMeta } from '../../core/types';
+import { Plugin } from '../static/spa';
+import { SwaggerConfig, StoredRoute, OpenAPISchema, SwaggerApplication } from './types';
+
+// ============================================
+// SWAGGER FEATURE (PLUGIN)
+// ============================================
+/**
+ * Create Swagger feature plugin for Nexus
+ *
+ * @example
+ * ```typescript
+ * // Minimal setup - auto-detects everything
+ * app.feature(swagger());
+ *
+ * // With custom info
+ * app.feature(swagger({
+ *   info: {
+ *     title: 'My Awesome API',
+ *     version: '2.0.0',
+ *     description: 'API documentation'
+ *   }
+ * }));
+ *
+ * // Full configuration
+ * app.feature(swagger({
+ *   path: '/api-docs',
+ *   specPath: '/swagger.json',
+ *   theme: 'dark',
+ *   securitySchemes: {
+ *     bearerAuth: {
+ *       type: 'http',
+ *       scheme: 'bearer',
+ *       bearerFormat: 'JWT'
+ *     }
+ *   }
+ * }));
+ * ```
+ */
+
+
+export function swagger(config: SwaggerConfig = {}): Plugin {
+  const resolvedConfig: SwaggerConfig = {
+    path: '/docs',
+    specPath: '/openapi.json',
+    docExpansion: 'list',
+    filter: true,
+    tryItOutEnabled: true,
+    persistAuthorization: true,
+    ...config,
+    info: {
+      title: 'API Documentation',
+      version: '1.0.0',
+      ...config.info
+    }
+  };
+
+  // Storage for routes - will be populated when app registers routes
+  const routes: StoredRoute[] = [];
+  const schemas: Map<string, OpenAPISchema> = new Map();
+  let serverUrl = '';
+  let appInstance: Application | null = null;
+
+  return {
+    name: 'swagger',
+    version: '1.0.0',
+
+    install(app: Application) {
+      appInstance = app;
+      // Cast to extended interface for swagger-specific properties
+      const swaggerApp = app as SwaggerApplication;
+      // Hook into route registration to capture routes with metadata
+      const originalRoute = app.route.bind(app);
+      const originalGet = app.get.bind(app);
+      const originalPost = app.post.bind(app);
+      const originalPut = app.put.bind(app);
+      const originalDelete = app.delete.bind(app);
+      const originalPatch = app.patch.bind(app);
+
+      // Override route method to capture metadata
+      app.route = function (routeConfig: RouteConfig) {
+        routes.push({
+          method: routeConfig.method,
+          path: routeConfig.path,
+          schema: routeConfig.schema,
+          meta: routeConfig.meta
+        });
+        return originalRoute(routeConfig);
+      };
+
+      // Override HTTP method shortcuts
+      const wrapMethod = (method: HTTPMethod, original: Function) => {
+        return function (pathOrRoute: string | any, handlerOrConfig?: any) {
+          // Class-based routing
+          if (typeof pathOrRoute === 'object' && 'pathName' in pathOrRoute) {
+            const route = pathOrRoute;
+            routes.push({
+              method,
+              path: route.pathName,
+              schema: route.schema?.(),
+              meta: route.meta?.()
+            });
+            return original(pathOrRoute);
+          }
+
+          const path = pathOrRoute;
+          if (typeof handlerOrConfig !== 'function' && handlerOrConfig) {
+            routes.push({
+              method,
+              path,
+              schema: handlerOrConfig.schema,
+              meta: handlerOrConfig.meta
+            });
+          } else {
+            routes.push({ method, path });
+          }
+          return original(path, handlerOrConfig);
+        };
+      };
+
+      app.get = wrapMethod('GET', originalGet);
+      app.post = wrapMethod('POST', originalPost);
+      app.put = wrapMethod('PUT', originalPut);
+      app.delete = wrapMethod('DELETE', originalDelete);
+      app.patch = wrapMethod('PATCH', originalPatch);
+
+      // Add swagger endpoints
+      const docsPath = resolvedConfig.path!;
+      const specPath = resolvedConfig.specPath!;
+
+      // Serve OpenAPI JSON spec
+      originalGet(specPath, async (ctx: Context) => {
+        // Auto-detect server URL from request
+        if (!serverUrl && ctx.raw?.req) {
+          const req = ctx.raw.req;
+          const protocol = req.headers['x-forwarded-proto'] || 'http';
+          const host = req.headers.host || 'localhost:3000';
+          serverUrl = `${protocol}://${host}`;
+        }
+
+        // Combine intercepted routes with routes from router (for file-based routing)
+        const allRoutes = getAllRoutes(routes, appInstance, docsPath, specPath);
+        const spec = generateSpec(allRoutes, schemas, resolvedConfig, serverUrl);
+        return ctx.json(spec);
+      });
+
+      // Serve Swagger UI
+      originalGet(docsPath, async (_ctx: Context) => {
+        const html = generateSwaggerUI(resolvedConfig);
+        return {
+          statusCode: 200,
+          headers: { 'Content-Type': 'text/html; charset=utf-8' },
+          body: html
+        };
+      });
+
+      // Also serve at /docs/ (with trailing slash)
+      originalGet(docsPath + '/', async (_ctx: Context) => {
+        const html = generateSwaggerUI(resolvedConfig);
+        return {
+          statusCode: 200,
+          headers: { 'Content-Type': 'text/html; charset=utf-8' },
+          body: html
+        };
+      });
+
+      // Add schema registration method to app
+      swaggerApp.swaggerSchema = (name: string, schema: OpenAPISchema) => {
+        schemas.set(name, schema);
+        return swaggerApp;
+      };
+
+      // Log swagger is enabled (check via environment or resolvedConfig)
+      if (process.env.DEBUG === 'true' || process.env.NODE_ENV === 'development') {
+        console.log(`📚 Swagger UI: ${docsPath}`);
+        console.log(`📄 OpenAPI Spec: ${specPath}`);
+      }
+    }
+  };
+}
+
+/**
+ * Get all routes by combining intercepted routes with routes from the router
+ * This ensures file-based routes are also included in Swagger docs
+ */
+function getAllRoutes(
+  interceptedRoutes: StoredRoute[],
+  app: Application | null,
+  docsPath: string,
+  specPath: string
+): StoredRoute[] {
+  // Create a Set of already tracked route keys (method + path)
+  const trackedKeys = new Set(
+    interceptedRoutes.map(r => `${r.method}:${r.path}`)
+  );
+
+  // Start with intercepted routes (filtered to exclude swagger routes)
+  const allRoutes: StoredRoute[] = interceptedRoutes.filter(
+    r => !r.path.startsWith(docsPath) && r.path !== specPath
+  );
+
+  // Get routes from router (includes file-based routes)
+  if (app) {
+    const routerRoutes = app.getRoutes() as Array<{
+      method: string;
+      path: string;
+      schema?: SchemaConfig;
+      meta?: RouteMeta;
+    }>;
+
+    for (const route of routerRoutes) {
+      const key = `${route.method}:${route.path}`;
+
+      // Skip if already tracked or is swagger route
+      if (
+        trackedKeys.has(key) ||
+        route.path.startsWith(docsPath) ||
+        route.path === specPath
+      ) {
+        continue;
+      }
+
+      allRoutes.push({
+        method: route.method as HTTPMethod,
+        path: route.path,
+        schema: route.schema,
+        meta: route.meta
+      });
+    }
+  }
+
+  // Sort routes by path for consistent ordering
+  return allRoutes.sort((a, b) => a.path.localeCompare(b.path));
+}