"use client"; import { useEffect } from 'react'; import SwaggerUI from 'swagger-ui-react'; export default function SwaggerPage() { useEffect(() => { // 设置页面标题 document.title = 'API Documentation - ShortURL Analytics'; // 动态添加Swagger UI CSS const link = document.createElement('link'); link.rel = 'stylesheet'; link.type = 'text/css'; link.href = 'https://unpkg.com/swagger-ui-dist@5.20.1/swagger-ui.css'; document.head.appendChild(link); // 清理函数 return () => { document.head.removeChild(link); }; }, []); // 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: '事件唯一标识符,用于唯一标识事件记录。若不提供则自动生成UUID' }, event_time: { type: 'string', format: 'date-time', description: '事件发生的时间戳(ISO 8601格式),记录事件发生的精确时间。若不提供则使用当前服务器时间' }, event_type: { type: 'string', enum: ['click', 'conversion', 'redirect', 'error'], description: '事件类型,用于分类不同的用户交互行为。click表示点击事件,conversion表示转化事件,redirect表示重定向事件,error表示错误事件' }, event_attributes: { type: 'string', description: '事件附加属性的JSON字符串,用于存储与特定事件相关的自定义数据,例如事件来源、关联活动ID等' }, // Link information link_id: { type: 'string', description: '短链接的唯一标识符,用于关联事件与特定短链接' }, link_slug: { type: 'string', description: '短链接的短码/slug部分,即URL路径中的短字符串,用于生成短链接URL' }, link_label: { type: 'string', description: '短链接的标签名称,用于分类和组织管理短链接' }, link_title: { type: 'string', description: '短链接的标题,用于在管理界面或分析报告中显示链接的易读名称' }, link_original_url: { type: 'string', format: 'uri', description: '短链接对应的原始目标URL,即用户访问短链接后将被重定向到的实际URL' }, link_attributes: { type: 'string', description: '链接附加属性的JSON字符串,用于存储与链接相关的自定义数据,如营销活动信息、目标受众等' }, link_created_at: { type: 'string', format: 'date-time', description: '短链接创建时间,记录链接何时被创建' }, link_expires_at: { type: 'string', format: 'date-time', nullable: true, description: '短链接过期时间,指定链接何时失效,值为null表示永不过期' }, link_tags: { type: 'string', description: '链接标签的JSON数组字符串,用于通过标签对链接进行分类和过滤' }, // User information user_id: { type: 'string', description: '创建链接的用户ID,用于跟踪哪个用户创建了短链接' }, user_name: { type: 'string', description: '用户名称,用于在报表中展示更易读的用户身份' }, user_email: { type: 'string', format: 'email', description: '用户电子邮件地址,可用于通知和报告分发' }, user_attributes: { type: 'string', description: '用户附加属性的JSON字符串,存储用户相关的额外信息,如订阅级别、账户创建日期等' }, // Team information team_id: { type: 'string', description: '团队ID,用于标识链接归属的团队,支持多团队使用场景' }, team_name: { type: 'string', description: '团队名称,用于在报表和管理界面中显示更友好的团队标识' }, team_attributes: { type: 'string', description: '团队附加属性的JSON字符串,存储团队相关的额外信息,如部门、地区等' }, // Project information project_id: { type: 'string', description: '项目ID,用于将链接归类到特定项目下,便于项目级别的分析' }, project_name: { type: 'string', description: '项目名称,提供更具描述性的项目标识,用于报表和管理界面' }, project_attributes: { type: 'string', description: '项目附加属性的JSON字符串,存储项目相关的额外信息,如目标、预算等' }, // QR code information qr_code_id: { type: 'string', description: '二维码ID,标识与事件关联的二维码,用于跟踪二维码的使用情况' }, qr_code_name: { type: 'string', description: '二维码名称,提供更具描述性的二维码标识,便于管理和报表' }, qr_code_attributes: { type: 'string', description: '二维码附加属性的JSON字符串,存储与二维码相关的额外信息,如尺寸、颜色、logo等' }, // Visitor information visitor_id: { type: 'string', format: 'uuid', description: '访问者唯一标识符,用于跟踪和识别独立访问者,分析用户行为' }, session_id: { type: 'string', description: '会话标识符,用于将同一访问者的多个事件分组到同一会话中' }, ip_address: { type: 'string', description: '访问者的IP地址,用于地理位置分析和安全监控' }, country: { type: 'string', description: '访问者所在国家,用于地理分布分析' }, city: { type: 'string', description: '访问者所在城市,提供更精细的地理位置分析' }, device_type: { type: 'string', description: '访问者使用的设备类型(如mobile、desktop、tablet等),用于设备分布分析' }, browser: { type: 'string', description: '访问者使用的浏览器(如Chrome、Safari、Firefox等),用于浏览器分布分析' }, os: { type: 'string', description: '访问者使用的操作系统(如iOS、Android、Windows等),用于操作系统分布分析' }, user_agent: { type: 'string', description: '访问者的User-Agent字符串,包含有关浏览器、操作系统和设备的详细信息' }, // Referrer information referrer: { type: 'string', description: '引荐来源URL,指示用户从哪个网站或页面访问短链接,用于分析流量来源' }, utm_source: { type: 'string', description: 'UTM来源参数,标识流量的来源渠道,如Google、Facebook、Newsletter等' }, utm_medium: { type: 'string', description: 'UTM媒介参数,标识营销媒介类型,如cpc、email、social等' }, utm_campaign: { type: 'string', description: 'UTM活动参数,标识特定的营销活动名称,用于跟踪不同活动的效果' }, // Interaction information time_spent_sec: { type: 'number', description: '用户停留时间(秒),表示用户在目标页面上花费的时间,用于分析用户参与度' }, is_bounce: { type: 'boolean', description: '是否为跳出访问,表示用户是否在查看单个页面后离开,不与网站进一步交互' }, is_qr_scan: { type: 'boolean', description: '是否来自二维码扫描,用于区分和分析二维码带来的流量' }, conversion_type: { type: 'string', description: '转化类型,表示事件触发的转化类型,如注册、购买、下载等,用于细分不同类型的转化' }, conversion_value: { type: 'number', description: '转化价值,表示转化事件的经济价值或重要性,如购买金额、潜在客户价值等' } } }, Event: { type: 'object', required: ['event_id', 'event_type', 'event_time', 'visitor_id'], properties: { event_id: { type: 'string', format: 'uuid', description: '事件唯一标识符,用于唯一标识事件记录', }, event_type: { type: 'string', enum: ['click', 'conversion'], description: '事件类型,用于分类不同的用户交互行为。click表示点击事件,conversion表示转化事件', }, event_time: { type: 'string', format: 'date-time', description: '事件发生的时间戳,记录事件发生的精确时间', }, link_id: { type: 'string', description: '短链接的唯一标识符,用于关联事件与特定短链接', }, link_slug: { type: 'string', description: '短链接的短码/slug部分,即URL路径中的短字符串', }, link_original_url: { type: 'string', format: 'uri', description: '短链接对应的原始目标URL,即用户访问短链接后将被重定向到的实际URL', }, visitor_id: { type: 'string', format: 'uuid', description: '访问者唯一标识符,用于跟踪和识别独立访问者,分析用户行为', }, device_type: { type: 'string', description: '访问者使用的设备类型(如mobile、desktop、tablet等),用于设备分布分析', }, browser: { type: 'string', description: '访问者使用的浏览器(如Chrome、Safari、Firefox等),用于浏览器分布分析', }, os: { type: 'string', description: '访问者使用的操作系统(如iOS、Android、Windows等),用于操作系统分布分析', }, country: { type: 'string', description: '访问者所在国家,用于地理分布分析', }, region: { type: 'string', description: '访问者所在地区/省份,提供中等精细度的地理位置分析', }, city: { type: 'string', description: '访问者所在城市,提供更精细的地理位置分析', }, referrer: { type: 'string', description: '引荐来源URL,指示用户从哪个网站或页面访问短链接,用于分析流量来源', }, conversion_type: { type: 'string', description: '转化类型,表示事件触发的转化类型,如注册、购买、下载等(仅当event_type为conversion时有效)', }, conversion_value: { type: 'number', description: '转化价值,表示转化事件的经济价值或重要性,如购买金额、潜在客户价值等(仅当event_type为conversion时有效)', }, }, }, EventsSummary: { type: 'object', required: ['totalEvents', 'uniqueVisitors'], properties: { totalEvents: { type: 'integer', description: '时间段内的事件总数,包括所有类型的事件总计', }, uniqueVisitors: { type: 'integer', description: '时间段内的独立访问者数量,基于唯一访问者ID计算', }, totalConversions: { type: 'integer', description: '时间段内的转化事件总数,用于衡量营销效果', }, averageTimeSpent: { type: 'number', description: '平均停留时间(秒),表示用户平均在目标页面上停留的时间,是用户参与度的重要指标', }, }, }, TimeSeriesData: { type: 'object', properties: { timestamp: { type: 'string', format: 'date-time', description: '时间序列中的时间点,表示数据采集的精确时间', }, events: { type: 'number', description: '该时间点的事件数量,显示事件随时间的分布趋势', }, visitors: { type: 'number', description: '该时间点的独立访问者数量,显示访问者随时间的分布趋势', }, conversions: { type: 'number', description: '该时间点的转化数量,显示转化随时间的分布趋势', }, }, }, GeoData: { type: 'object', properties: { location: { type: 'string', description: '位置标识符,可以是国家、地区或城市的组合标识', }, country: { type: 'string', description: '国家名称,表示访问者所在的国家', }, region: { type: 'string', description: '地区/省份名称,表示访问者所在的地区或省份', }, city: { type: 'string', description: '城市名称,表示访问者所在的城市', }, visits: { type: 'number', description: '来自该位置的访问次数,用于分析不同地区的流量分布', }, visitors: { type: 'number', description: '来自该位置的独立访问者数量,用于分析不同地区的用户分布', }, percentage: { type: 'number', description: '占总访问量的百分比,便于直观比较不同地区的流量占比', }, }, }, DeviceAnalytics: { type: 'object', properties: { deviceTypes: { type: 'array', items: { type: 'object', properties: { type: { type: 'string', description: '设备类型,如mobile、desktop、tablet等,用于设备类型分析', }, count: { type: 'number', description: '使用该设备类型的访问次数,用于统计各类设备的使用情况', }, percentage: { type: 'number', description: '该设备类型占总访问量的百分比,便于比较不同设备类型的使用占比', }, }, }, }, browsers: { type: 'array', items: { type: 'object', properties: { name: { type: 'string', description: '浏览器名称,如Chrome、Safari、Firefox等,用于浏览器使用分析', }, count: { type: 'number', description: '使用该浏览器的访问次数,用于统计各类浏览器的使用情况', }, percentage: { type: 'number', description: '该浏览器占总访问量的百分比,便于比较不同浏览器的使用占比', }, }, }, }, operatingSystems: { type: 'array', items: { type: 'object', properties: { name: { type: 'string', description: '操作系统名称,如iOS、Android、Windows等,用于操作系统使用分析', }, count: { type: 'number', description: '使用该操作系统的访问次数,用于统计各类操作系统的使用情况', }, percentage: { type: 'number', description: '该操作系统占总访问量的百分比,便于比较不同操作系统的使用占比', }, }, }, }, }, }, Pagination: { type: 'object', required: ['page', 'pageSize', 'totalItems', 'totalPages'], properties: { page: { type: 'integer', description: '当前页码,表示结果集中的当前页面位置', }, pageSize: { type: 'integer', description: '每页项目数,表示每页显示的结果数量', }, totalItems: { type: 'integer', description: '总项目数,表示符合查询条件的结果总数', }, totalPages: { type: 'integer', description: '总页数,基于总项目数和每页项目数计算得出', }, }, }, Error: { type: 'object', required: ['code', 'message'], properties: { code: { type: 'string', description: '错误代码,用于标识特定类型的错误,便于客户端处理不同错误情况', }, message: { type: 'string', description: '错误消息,提供关于错误的人类可读描述,帮助理解错误原因', }, }, }, }, }, }; return (

API Documentation

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

); }