swagger configure

app/(app)/analytics/devices/page.tsx

@@ -1,7 +1,8 @@
 "use client";
 
 import { useState, useEffect, useRef } from 'react';
-import { DeviceAnalytics } from '../../api/types';
+import { fetchData } from '@/app/api/utils';
+import { DeviceAnalytics } from '@/app/api/types';
 import { Chart, PieController, ArcElement, Tooltip, Legend, CategoryScale, LinearScale } from 'chart.js';
 
 // 注册Chart.js组件

app/(app)/dashboard/page.tsx

@@ -2,11 +2,11 @@
 
 import { useState, useEffect } from 'react';
 import { addDays, format } from 'date-fns';
-import { DateRangePicker } from '../components/ui/DateRangePicker';
+import { DateRangePicker } from '@/app/components/ui/DateRangePicker';
-import TimeSeriesChart from '../components/charts/TimeSeriesChart';
+import TimeSeriesChart from '@/app/components/charts/TimeSeriesChart';
-import GeoAnalytics from '../components/analytics/GeoAnalytics';
+import GeoAnalytics from '@/app/components/analytics/GeoAnalytics';
-import DeviceAnalytics from '../components/analytics/DeviceAnalytics';
+import DeviceAnalytics from '@/app/components/analytics/DeviceAnalytics';
-import { EventsSummary, TimeSeriesData, GeoData, DeviceAnalytics as DeviceAnalyticsType } from '../api/types';
+import { EventsSummary, TimeSeriesData, GeoData, DeviceAnalytics as DeviceAnalyticsType } from '@/app/api/types';
 
 export default function DashboardPage() {
   const [dateRange, setDateRange] = useState({

app/(app)/events/page.tsx

@@ -1,9 +1,9 @@
 "use client";
 
 import { useState, useEffect } from 'react';
-import { format } from 'date-fns';
+import { addDays, format } from 'date-fns';
-import { DateRangePicker } from '../components/ui/DateRangePicker';
+import { DateRangePicker } from '@/app/components/ui/DateRangePicker';
-import { Event } from '../api/types';
+import { Event } from '@/app/api/types';
 
 export default function EventsPage() {
   const [dateRange, setDateRange] = useState({

app/(app)/layout.tsx

@@ -0,0 +1,66 @@
+import '../globals.css';
+import type { Metadata } from 'next';
+import { Inter } from 'next/font/google';
+import Link from 'next/link';
+
+const inter = Inter({ subsets: ['latin'] });
+
+export const metadata: Metadata = {
+  title: 'ShortURL Analytics',
+  description: 'Analytics dashboard for ShortURL service',
+};
+
+export default function AppLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <div className={inter.className}>
+      <div className="min-h-screen bg-gray-50 dark:bg-gray-900">
+        <nav className="bg-white dark:bg-gray-800 border-b border-gray-200 dark:border-gray-700">
+          <div className="container mx-auto px-4">
+            <div className="flex items-center justify-between h-16">
+              <div className="flex items-center">
+                <Link href="/" className="text-xl font-bold text-gray-900 dark:text-gray-100">
+                  ShortURL Analytics
+                </Link>
+                <div className="hidden md:block ml-10">
+                  <div className="flex items-baseline space-x-4">
+                    <Link
+                      href="/dashboard"
+                      className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
+                    >
+                      Dashboard
+                    </Link>
+                    <Link
+                      href="/events"
+                      className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
+                    >
+                      Events
+                    </Link>
+                    <Link
+                      href="/analytics/geo"
+                      className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
+                    >
+                      Geographic
+                    </Link>
+                    <Link
+                      href="/analytics/devices"
+                      className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
+                    >
+                      Devices
+                    </Link>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </nav>
+        <main className="py-10">
+          {children}
+        </main>
+      </div>
+    </div>
+  );
+} 

app/(app)/page.tsx

@@ -0,0 +1,59 @@
+import Link from 'next/link';
+
+export default function Home() {
+  return (
+    <div className="container mx-auto px-4">
+      <div className="max-w-2xl mx-auto py-16">
+        <h1 className="text-4xl font-bold text-gray-900 dark:text-gray-100 mb-8">
+          Welcome to ShortURL Analytics
+        </h1>
+        <div className="grid gap-6">
+          <Link
+            href="/dashboard"
+            className="block p-6 bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow"
+          >
+            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-2">
+              Dashboard
+            </h2>
+            <p className="text-gray-600 dark:text-gray-400">
+              View your overall analytics and key metrics
+            </p>
+          </Link>
+          <Link
+            href="/events"
+            className="block p-6 bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow"
+          >
+            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-2">
+              Events
+            </h2>
+            <p className="text-gray-600 dark:text-gray-400">
+              Track and analyze event data
+            </p>
+          </Link>
+          <Link
+            href="/analytics/geo"
+            className="block p-6 bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow"
+          >
+            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-2">
+              Geographic Analysis
+            </h2>
+            <p className="text-gray-600 dark:text-gray-400">
+              Explore visitor locations and geographic patterns
+            </p>
+          </Link>
+          <Link
+            href="/analytics/devices"
+            className="block p-6 bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-md transition-shadow"
+          >
+            <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100 mb-2">
+              Device Analytics
+            </h2>
+            <p className="text-gray-600 dark:text-gray-400">
+              Understand how users access your links
+            </p>
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+} 

app/(swagger)/swagger/page.tsx

@@ -0,0 +1,518 @@
+"use client";
+
+import { useEffect } from 'react';
+import SwaggerUI from 'swagger-ui-react';
+import 'swagger-ui-react/swagger-ui.css';
+
+export default function SwaggerPage() {
+  useEffect(() => {
+    // 设置页面标题
+    document.title = 'API Documentation - ShortURL Analytics';
+  }, []);
+
+  // Swagger配置
+  const swaggerConfig = {
+    openapi: '3.0.0',
+    info: {
+      title: 'ShortURL Analytics API',
+      version: '1.0.0',
+      description: 'API documentation for ShortURL Analytics service',
+      contact: {
+        name: 'API Support',
+        email: 'support@example.com',
+      },
+      license: {
+        name: 'MIT',
+        url: 'https://opensource.org/licenses/MIT',
+      },
+    },
+    servers: [
+      {
+        url: '/api',
+        description: 'API Server',
+      },
+    ],
+    tags: [
+      {
+        name: 'events',
+        description: 'Event tracking and analytics endpoints',
+      },
+    ],
+    paths: {
+      '/events': {
+        get: {
+          tags: ['events'],
+          summary: 'Get events',
+          description: 'Retrieve events within a specified time range with pagination support',
+          parameters: [
+            {
+              name: 'startTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'Start time for events query (ISO 8601 format)',
+            },
+            {
+              name: 'endTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'End time for events query (ISO 8601 format)',
+            },
+            {
+              name: 'page',
+              in: 'query',
+              schema: {
+                type: 'integer',
+                default: 1,
+                minimum: 1,
+              },
+              description: 'Page number for pagination',
+            },
+            {
+              name: 'pageSize',
+              in: 'query',
+              schema: {
+                type: 'integer',
+                default: 50,
+                minimum: 1,
+                maximum: 100,
+              },
+              description: 'Number of items per page',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      data: {
+                        type: 'array',
+                        items: {
+                          $ref: '#/components/schemas/Event',
+                        },
+                      },
+                      pagination: {
+                        $ref: '#/components/schemas/Pagination',
+                      },
+                    },
+                  },
+                },
+              },
+            },
+            '400': {
+              description: 'Bad request',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Error',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/events/summary': {
+        get: {
+          tags: ['events'],
+          summary: 'Get events summary',
+          description: 'Get aggregated statistics for events within a specified time range',
+          parameters: [
+            {
+              name: 'startTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'Start time for summary (ISO 8601 format)',
+            },
+            {
+              name: 'endTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+              description: 'End time for summary (ISO 8601 format)',
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/EventsSummary',
+                  },
+                },
+              },
+            },
+            '400': {
+              description: 'Bad request',
+              content: {
+                'application/json': {
+                  schema: {
+                    $ref: '#/components/schemas/Error',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/events/time-series': {
+        get: {
+          summary: 'Get time series data',
+          parameters: [
+            {
+              name: 'startTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+            },
+            {
+              name: 'endTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      data: {
+                        type: 'array',
+                        items: {
+                          $ref: '#/components/schemas/TimeSeriesData',
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/events/geo': {
+        get: {
+          summary: 'Get geographic data',
+          parameters: [
+            {
+              name: 'startTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+            },
+            {
+              name: 'endTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      data: {
+                        type: 'array',
+                        items: {
+                          $ref: '#/components/schemas/GeoData',
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      '/events/devices': {
+        get: {
+          summary: 'Get device analytics data',
+          parameters: [
+            {
+              name: 'startTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+            },
+            {
+              name: 'endTime',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+                format: 'date-time',
+              },
+            },
+          ],
+          responses: {
+            '200': {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      data: {
+                        $ref: '#/components/schemas/DeviceAnalytics',
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        Event: {
+          type: 'object',
+          required: ['event_id', 'event_type', 'event_time', 'visitor_id'],
+          properties: {
+            event_id: {
+              type: 'string',
+              format: 'uuid',
+              description: 'Unique identifier for the event',
+            },
+            event_type: {
+              type: 'string',
+              enum: ['click', 'conversion'],
+              description: 'Type of the event',
+            },
+            event_time: {
+              type: 'string',
+              format: 'date-time',
+              description: 'Time when the event occurred',
+            },
+            link_id: {
+              type: 'string',
+              description: 'ID of the associated short link',
+            },
+            link_slug: {
+              type: 'string',
+              description: 'Slug of the short link',
+            },
+            link_original_url: {
+              type: 'string',
+              format: 'uri',
+              description: 'Original URL of the short link',
+            },
+            visitor_id: {
+              type: 'string',
+              format: 'uuid',
+              description: 'Unique identifier for the visitor',
+            },
+            device_type: {
+              type: 'string',
+              description: 'Type of device used',
+            },
+            browser: {
+              type: 'string',
+              description: 'Browser used',
+            },
+            os: {
+              type: 'string',
+              description: 'Operating system used',
+            },
+            country: {
+              type: 'string',
+              description: 'Country of the visitor',
+            },
+            region: {
+              type: 'string',
+              description: 'Region/state of the visitor',
+            },
+            city: {
+              type: 'string',
+              description: 'City of the visitor',
+            },
+            referrer: {
+              type: 'string',
+              description: 'Referrer URL',
+            },
+            conversion_type: {
+              type: 'string',
+              description: 'Type of conversion (if event_type is conversion)',
+            },
+            conversion_value: {
+              type: 'number',
+              description: 'Value of the conversion (if applicable)',
+            },
+          },
+        },
+        EventsSummary: {
+          type: 'object',
+          required: ['totalEvents', 'uniqueVisitors'],
+          properties: {
+            totalEvents: {
+              type: 'integer',
+              description: 'Total number of events in the period',
+            },
+            uniqueVisitors: {
+              type: 'integer',
+              description: 'Number of unique visitors',
+            },
+            totalConversions: {
+              type: 'integer',
+              description: 'Total number of conversions',
+            },
+            averageTimeSpent: {
+              type: 'number',
+              description: 'Average time spent in seconds',
+            },
+          },
+        },
+        TimeSeriesData: {
+          type: 'object',
+          properties: {
+            timestamp: { type: 'string', format: 'date-time' },
+            events: { type: 'number' },
+            visitors: { type: 'number' },
+            conversions: { type: 'number' },
+          },
+        },
+        GeoData: {
+          type: 'object',
+          properties: {
+            location: { type: 'string' },
+            country: { type: 'string' },
+            region: { type: 'string' },
+            city: { type: 'string' },
+            visits: { type: 'number' },
+            visitors: { type: 'number' },
+            percentage: { type: 'number' },
+          },
+        },
+        DeviceAnalytics: {
+          type: 'object',
+          properties: {
+            deviceTypes: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  type: { type: 'string' },
+                  count: { type: 'number' },
+                  percentage: { type: 'number' },
+                },
+              },
+            },
+            browsers: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  name: { type: 'string' },
+                  count: { type: 'number' },
+                  percentage: { type: 'number' },
+                },
+              },
+            },
+            operatingSystems: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  name: { type: 'string' },
+                  count: { type: 'number' },
+                  percentage: { type: 'number' },
+                },
+              },
+            },
+          },
+        },
+        Pagination: {
+          type: 'object',
+          required: ['page', 'pageSize', 'totalItems', 'totalPages'],
+          properties: {
+            page: {
+              type: 'integer',
+              description: 'Current page number',
+            },
+            pageSize: {
+              type: 'integer',
+              description: 'Number of items per page',
+            },
+            totalItems: {
+              type: 'integer',
+              description: 'Total number of items',
+            },
+            totalPages: {
+              type: 'integer',
+              description: 'Total number of pages',
+            },
+          },
+        },
+        Error: {
+          type: 'object',
+          required: ['code', 'message'],
+          properties: {
+            code: {
+              type: 'string',
+              description: 'Error code',
+            },
+            message: {
+              type: 'string',
+              description: 'Error message',
+            },
+          },
+        },
+      },
+    },
+  };
+
+  return (
+    <div className="container mx-auto px-4 py-8">
+      <div className="mb-8">
+        <h1 className="text-3xl font-bold mb-2">API Documentation</h1>
+        <p className="text-gray-600">
+          Explore and test the ShortURL Analytics API endpoints using the interactive documentation below.
+        </p>
+      </div>
+      <SwaggerUI spec={swaggerConfig} />
+    </div>
+  );
+} 

app/components/analytics/DeviceAnalytics.tsx

@@ -1,6 +1,8 @@
 "use client";
 
-import { DeviceAnalytics as DeviceAnalyticsType } from '../../api/types';
+import { useEffect, useRef } from 'react';
+import { DeviceAnalytics as DeviceAnalyticsType } from '@/app/api/types';
+import { Chart, PieController, ArcElement, Tooltip, Legend } from 'chart.js';
 
 interface DeviceAnalyticsProps {
   data: DeviceAnalyticsType;

app/components/analytics/GeoAnalytics.tsx

@@ -1,6 +1,8 @@
 "use client";
 
-import { GeoData } from '../../api/types';
+import { useEffect, useRef } from 'react';
+import { GeoData } from '@/app/api/types';
+import { Chart, PieController, ArcElement, Tooltip, Legend } from 'chart.js';
 
 interface GeoAnalyticsProps {
   data: GeoData[];

app/components/charts/TimeSeriesChart.tsx

@@ -16,7 +16,7 @@ import {
   ChartOptions,
   TooltipItem
 } from 'chart.js';
-import { TimeSeriesData } from '../../api/types';
+import { TimeSeriesData } from '@/app/api/types';
 
 // 注册 Chart.js 组件
 ChartJS.register(

app/layout.tsx

@@ -1,68 +1,21 @@
 import './globals.css';
 import type { Metadata } from 'next';
-import { Inter } from 'next/font/google';
-import Link from 'next/link';
-
-const inter = Inter({ subsets: ['latin'] });
 
 export const metadata: Metadata = {
-  title: 'ShortURL Analytics',
+  title: 'Link Management & Analytics',
-  description: 'Analytics dashboard for ShortURL service',
+  description: 'Track and analyze shortened links',
 };
 
 export default function RootLayout({
   children,
-}: {
+}: Readonly<{
   children: React.ReactNode;
-}) {
+}>) {
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
-      <body className={inter.className}>
+      <body>
-        <div className="min-h-screen bg-gray-50 dark:bg-gray-900">
+        {children}
-          <nav className="bg-white dark:bg-gray-800 border-b border-gray-200 dark:border-gray-700">
-            <div className="container mx-auto px-4">
-              <div className="flex items-center justify-between h-16">
-                <div className="flex items-center">
-                  <Link href="/" className="text-xl font-bold text-gray-900 dark:text-gray-100">
-                    ShortURL Analytics
-                  </Link>
-                  <div className="hidden md:block ml-10">
-                    <div className="flex items-baseline space-x-4">
-                      <Link
-                        href="/dashboard"
-                        className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
-                      >
-                        Dashboard
-                      </Link>
-                      <Link
-                        href="/events"
-                        className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
-                      >
-                        Events
-                      </Link>
-                      <Link
-                        href="/analytics/geo"
-                        className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
-                      >
-                        Geographic
-                      </Link>
-                      <Link
-                        href="/analytics/devices"
-                        className="text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 px-3 py-2 rounded-md text-sm font-medium"
-                      >
-                        Devices
-                      </Link>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            </div>
-          </nav>
-          <main className="py-10">
-            {children}
-          </main>
-        </div>
       </body>
     </html>
   );
-}
+} 

app/layouts.tsx

@@ -1,21 +0,0 @@
-import './globals.css';
-import type { Metadata } from 'next';
-
-export const metadata: Metadata = {
-  title: 'Link Management & Analytics',
-  description: 'Track and analyze shortened links',
-};
-
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return (
-    <html lang="en" suppressHydrationWarning>
-      <body>
-        {children}
-      </body>
-    </html>
-  );
-} 

next.config.js

@@ -0,0 +1,13 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['swagger-ui-react'],
+  webpack: (config) => {
+    config.module.rules.push({
+      test: /\.css$/,
+      use: ['style-loader', 'css-loader'],
+    });
+    return config;
+  },
+};
+
+module.exports = nextConfig; 

package.json

@@ -33,6 +33,8 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "recharts": "^2.15.1",
+    "swagger-ui-dist": "^5.12.0",
+    "swagger-ui-react": "^5.12.0",
     "uuid": "^10.0.0"
   },
   "devDependencies": {
@@ -41,10 +43,13 @@
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@types/swagger-ui-react": "^4.18.3",
+    "css-loader": "^7.1.2",
     "eslint": "^9",
     "eslint-config-next": "15.2.3",
+    "style-loader": "^4.0.0",
     "tailwindcss": "^4",
     "typescript": "^5"
   },
   "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
-}
+}