"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/track': { post: { tags: ['events'], summary: 'Track new event', description: 'Record a new event in the analytics system', requestBody: { required: true, content: { 'application/json': { schema: { $ref: '#/components/schemas/EventInput', }, examples: { clickEvent: { summary: 'Basic click event', value: { event_type: 'click', link_id: 'link_123', link_slug: 'promo2023', link_original_url: 'https://example.com/promotion', visitor_id: '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b' } }, conversionEvent: { summary: 'Conversion event', value: { event_type: 'conversion', link_id: 'link_123', link_slug: 'promo2023', visitor_id: '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b', conversion_type: 'purchase', conversion_value: 99.99 } }, completeEvent: { summary: 'Complete event with all fields', value: { // Core event fields event_id: '123e4567-e89b-12d3-a456-426614174000', event_time: '2025-03-26T10:30:00.000Z', event_type: 'click', event_attributes: '{"source":"email_campaign","campaign_id":"spring_sale_2025"}', // Link information link_id: 'link_abc123', link_slug: 'summer-promo', link_label: 'Summer Promotion 2025', link_title: 'Summer Sale 50% Off', link_original_url: 'https://example.com/summer-sale-2025', link_attributes: '{"utm_campaign":"summer_2025","discount_code":"SUMMER50"}', link_created_at: '2025-03-20T08:00:00.000Z', link_expires_at: '2025-09-30T23:59:59.000Z', link_tags: '["promotion","summer","sale"]', // User information user_id: 'user_12345', user_name: 'John Doe', user_email: 'john.doe@example.com', user_attributes: '{"subscription_tier":"premium","account_created":"2024-01-15"}', // Team information team_id: 'team_67890', team_name: 'Marketing Team', team_attributes: '{"department":"marketing","region":"APAC"}', // Project information project_id: 'proj_54321', project_name: 'Summer Campaign 2025', project_attributes: '{"goals":"increase_sales","budget":"10000"}', // QR code information qr_code_id: 'qr_98765', qr_code_name: 'Summer Flyer QR', qr_code_attributes: '{"size":"large","color":"#FF5500","logo":true}', // Visitor information visitor_id: '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b', session_id: '7fc1bd8f-22d1-54eb-986f-3b9be5ecaf1c', ip_address: '203.0.113.42', country: 'United States', city: 'San Francisco', device_type: 'mobile', browser: 'Chrome', os: 'iOS', user_agent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.5 Mobile/15E148 Safari/604.1', // Referrer information referrer: 'https://www.google.com/search?q=summer+sale', utm_source: 'google', utm_medium: 'organic', utm_campaign: 'summer_promotion', // Interaction information time_spent_sec: 145, is_bounce: false, is_qr_scan: true, conversion_type: 'signup', conversion_value: 0 } } } } } }, responses: { '201': { description: 'Event successfully tracked', content: { 'application/json': { schema: { type: 'object', properties: { success: { type: 'boolean', example: true }, message: { type: 'string', example: 'Event tracked successfully' }, event_id: { type: 'string', format: 'uuid', example: '123e4567-e89b-12d3-a456-426614174000' } } } } } }, '400': { description: 'Bad request', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' }, example: { error: 'Missing required field: event_type' } } } }, '500': { description: 'Server error', content: { 'application/json': { schema: { type: 'object', properties: { error: { type: 'string' }, details: { type: 'string' } } }, example: { error: 'Failed to track event', details: 'Database connection error' } } } } } } }, '/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: { tags: ['events'], summary: 'Get time series data', description: 'Get time-based analytics data for events', parameters: [ { name: 'startTime', in: 'query', required: true, schema: { type: 'string', format: 'date-time', }, description: 'Start time for time series data (ISO 8601 format)', }, { name: 'endTime', in: 'query', required: true, schema: { type: 'string', format: 'date-time', }, description: 'End time for time series data (ISO 8601 format)', }, ], responses: { '200': { description: 'Successful response', content: { 'application/json': { schema: { type: 'object', properties: { data: { type: 'array', items: { $ref: '#/components/schemas/TimeSeriesData', }, }, }, }, }, }, }, '400': { description: 'Bad request', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error', }, }, }, }, }, }, }, '/events/geo': { get: { tags: ['events'], summary: 'Get geographic data', description: 'Get geographic distribution of events', parameters: [ { name: 'startTime', in: 'query', required: true, schema: { type: 'string', format: 'date-time', }, description: 'Start time for geographic data (ISO 8601 format)', }, { name: 'endTime', in: 'query', required: true, schema: { type: 'string', format: 'date-time', }, description: 'End time for geographic data (ISO 8601 format)', }, ], responses: { '200': { description: 'Successful response', content: { 'application/json': { schema: { type: 'object', properties: { data: { type: 'array', items: { $ref: '#/components/schemas/GeoData', }, }, }, }, }, }, }, '400': { description: 'Bad request', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error', }, }, }, }, }, }, }, '/events/devices': { get: { tags: ['events'], summary: 'Get device analytics data', description: 'Get device-related analytics for events', parameters: [ { name: 'startTime', in: 'query', required: true, schema: { type: 'string', format: 'date-time', }, description: 'Start time for device analytics (ISO 8601 format)', }, { name: 'endTime', in: 'query', required: true, schema: { type: 'string', format: 'date-time', }, description: 'End time for device analytics (ISO 8601 format)', }, ], responses: { '200': { description: 'Successful response', content: { 'application/json': { schema: { type: 'object', properties: { data: { $ref: '#/components/schemas/DeviceAnalytics', }, }, }, }, }, }, '400': { description: 'Bad request', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error', }, }, }, }, }, }, }, }, components: { schemas: { EventInput: { type: 'object', required: ['event_type'], properties: { // Core event fields event_id: { type: 'string', format: 'uuid', description: 'Unique identifier for the event (auto-generated if not provided)' }, event_time: { type: 'string', format: 'date-time', description: 'Time when the event occurred (defaults to current time if not provided)' }, event_type: { type: 'string', enum: ['click', 'conversion', 'redirect', 'error'], description: 'Type of the event' }, event_attributes: { type: 'string', description: 'JSON string with additional event attributes' }, // Link information link_id: { type: 'string', description: 'ID of the associated short link' }, link_slug: { type: 'string', description: 'Slug of the short link' }, link_label: { type: 'string', description: 'Label of the short link' }, link_title: { type: 'string', description: 'Title of the short link' }, link_original_url: { type: 'string', format: 'uri', description: 'Original URL of the short link' }, link_attributes: { type: 'string', description: 'JSON string with additional link attributes' }, link_created_at: { type: 'string', format: 'date-time', description: 'Creation time of the link' }, link_expires_at: { type: 'string', format: 'date-time', nullable: true, description: 'Expiration time of the link' }, link_tags: { type: 'string', description: 'JSON array with link tags' }, // User information user_id: { type: 'string', description: 'ID of the user who created the link' }, user_name: { type: 'string', description: 'Name of the user' }, user_email: { type: 'string', format: 'email', description: 'Email of the user' }, user_attributes: { type: 'string', description: 'JSON string with additional user attributes' }, // Team information team_id: { type: 'string', description: 'ID of the team' }, team_name: { type: 'string', description: 'Name of the team' }, team_attributes: { type: 'string', description: 'JSON string with additional team attributes' }, // Project information project_id: { type: 'string', description: 'ID of the project' }, project_name: { type: 'string', description: 'Name of the project' }, project_attributes: { type: 'string', description: 'JSON string with additional project attributes' }, // QR code information qr_code_id: { type: 'string', description: 'ID of the QR code' }, qr_code_name: { type: 'string', description: 'Name of the QR code' }, qr_code_attributes: { type: 'string', description: 'JSON string with additional QR code attributes' }, // Visitor information visitor_id: { type: 'string', format: 'uuid', description: 'Unique identifier for the visitor' }, session_id: { type: 'string', description: 'Session identifier' }, ip_address: { type: 'string', description: 'IP address of the visitor' }, country: { type: 'string', description: 'Country of the visitor' }, city: { type: 'string', description: 'City of the visitor' }, device_type: { type: 'string', description: 'Type of device used' }, browser: { type: 'string', description: 'Browser used' }, os: { type: 'string', description: 'Operating system used' }, user_agent: { type: 'string', description: 'User agent string' }, // Referrer information referrer: { type: 'string', description: 'Referrer URL' }, utm_source: { type: 'string', description: 'UTM source parameter' }, utm_medium: { type: 'string', description: 'UTM medium parameter' }, utm_campaign: { type: 'string', description: 'UTM campaign parameter' }, // Interaction information time_spent_sec: { type: 'number', description: 'Time spent in seconds' }, is_bounce: { type: 'boolean', description: 'Whether this was a bounce visit' }, is_qr_scan: { type: 'boolean', description: 'Whether this event came from a QR code scan' }, conversion_type: { type: 'string', description: 'Type of conversion' }, conversion_value: { type: 'number', description: 'Value of the conversion' } } }, 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', description: 'Time point in the series', }, events: { type: 'number', description: 'Number of events at this time point', }, visitors: { type: 'number', description: 'Number of unique visitors at this time point', }, conversions: { type: 'number', description: 'Number of conversions at this time point', }, }, }, GeoData: { type: 'object', properties: { location: { type: 'string', description: 'Location identifier', }, country: { type: 'string', description: 'Country name', }, region: { type: 'string', description: 'Region/state name', }, city: { type: 'string', description: 'City name', }, visits: { type: 'number', description: 'Number of visits from this location', }, visitors: { type: 'number', description: 'Number of unique visitors from this location', }, percentage: { type: 'number', description: 'Percentage of total visits', }, }, }, DeviceAnalytics: { type: 'object', properties: { deviceTypes: { type: 'array', items: { type: 'object', properties: { type: { type: 'string', description: 'Device type', }, count: { type: 'number', description: 'Number of visits from this device type', }, percentage: { type: 'number', description: 'Percentage of total visits', }, }, }, }, browsers: { type: 'array', items: { type: 'object', properties: { name: { type: 'string', description: 'Browser name', }, count: { type: 'number', description: 'Number of visits from this browser', }, percentage: { type: 'number', description: 'Percentage of total visits', }, }, }, }, operatingSystems: { type: 'array', items: { type: 'object', properties: { name: { type: 'string', description: 'Operating system name', }, count: { type: 'number', description: 'Number of visits from this OS', }, percentage: { type: 'number', description: 'Percentage of total visits', }, }, }, }, }, }, 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 (

API Documentation

Explore and test the ShortURL Analytics API endpoints using the interactive documentation below.

); }