1235 lines
43 KiB
TypeScript
1235 lines
43 KiB
TypeScript
"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 with pagination and filtering support. If startTime and endTime are not provided, will return the most recent events.',
|
||
parameters: [
|
||
{
|
||
name: 'startTime',
|
||
in: 'query',
|
||
required: false,
|
||
schema: {
|
||
type: 'string',
|
||
format: 'date-time',
|
||
},
|
||
description: 'Start time for events query (ISO 8601 format). If not provided, no lower time bound will be applied.',
|
||
},
|
||
{
|
||
name: 'endTime',
|
||
in: 'query',
|
||
required: false,
|
||
schema: {
|
||
type: 'string',
|
||
format: 'date-time',
|
||
},
|
||
description: 'End time for events query (ISO 8601 format). If not provided, no upper time bound will be applied.',
|
||
},
|
||
{
|
||
name: 'eventType',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'string',
|
||
enum: ['click', 'redirect', 'conversion', 'error']
|
||
},
|
||
description: 'Filter events by type',
|
||
},
|
||
{
|
||
name: 'linkId',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'string'
|
||
},
|
||
description: 'Filter events by link ID',
|
||
},
|
||
{
|
||
name: 'linkSlug',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'string'
|
||
},
|
||
description: 'Filter events by link slug',
|
||
},
|
||
{
|
||
name: 'userId',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'string'
|
||
},
|
||
description: 'Filter events by user ID',
|
||
},
|
||
{
|
||
name: 'teamId',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'string'
|
||
},
|
||
description: 'Filter events by team ID',
|
||
},
|
||
{
|
||
name: 'projectId',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'string'
|
||
},
|
||
description: 'Filter events by project ID',
|
||
},
|
||
{
|
||
name: 'tags',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'string'
|
||
},
|
||
description: 'Filter events by tags (comma-separated list)',
|
||
example: 'promo,vip,summer'
|
||
},
|
||
{
|
||
name: 'searchSlug',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'string'
|
||
},
|
||
description: 'Search events by partial link slug match',
|
||
},
|
||
{
|
||
name: 'page',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'integer',
|
||
default: 1,
|
||
minimum: 1,
|
||
},
|
||
description: 'Page number for pagination',
|
||
},
|
||
{
|
||
name: 'pageSize',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'integer',
|
||
default: 20,
|
||
minimum: 1,
|
||
maximum: 100,
|
||
},
|
||
description: 'Number of items per page',
|
||
},
|
||
{
|
||
name: 'sortBy',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'string',
|
||
enum: ['event_time', 'event_type', 'link_slug', 'conversion_value']
|
||
},
|
||
description: 'Field to sort by',
|
||
},
|
||
{
|
||
name: 'sortOrder',
|
||
in: 'query',
|
||
schema: {
|
||
type: 'string',
|
||
enum: ['asc', 'desc'],
|
||
default: 'desc'
|
||
},
|
||
description: 'Sort order',
|
||
}
|
||
],
|
||
responses: {
|
||
'200': {
|
||
description: 'Successful response',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: {
|
||
type: 'boolean',
|
||
example: true
|
||
},
|
||
data: {
|
||
type: 'array',
|
||
items: {
|
||
$ref: '#/components/schemas/Event'
|
||
}
|
||
},
|
||
meta: {
|
||
type: 'object',
|
||
properties: {
|
||
total: {
|
||
type: 'number',
|
||
description: 'Total number of events matching the filters'
|
||
},
|
||
page: {
|
||
type: 'number',
|
||
description: 'Current page number'
|
||
},
|
||
pageSize: {
|
||
type: 'number',
|
||
description: 'Number of items per page'
|
||
},
|
||
filters: {
|
||
type: 'object',
|
||
properties: {
|
||
tags: {
|
||
type: 'array',
|
||
items: {
|
||
type: 'string'
|
||
},
|
||
description: 'Applied tag filters'
|
||
},
|
||
teamId: {
|
||
type: 'string',
|
||
description: 'Applied team filter'
|
||
},
|
||
projectId: {
|
||
type: 'string',
|
||
description: 'Applied project filter'
|
||
},
|
||
searchSlug: {
|
||
type: 'string',
|
||
description: 'Applied slug search term'
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
example: {
|
||
success: true,
|
||
data: [
|
||
{
|
||
event_id: '123e4567-e89b-12d3-a456-426614174000',
|
||
event_time: '2024-03-31T10:00:00.000Z',
|
||
event_type: 'click',
|
||
link_slug: 'summer-promo',
|
||
link_tags: ['promo', 'summer'],
|
||
team_id: 'team1',
|
||
project_id: 'proj1'
|
||
}
|
||
],
|
||
meta: {
|
||
total: 150,
|
||
page: 1,
|
||
pageSize: 20,
|
||
filters: {
|
||
tags: ['promo', 'summer'],
|
||
teamId: 'team1',
|
||
projectId: 'proj1',
|
||
searchSlug: 'summer'
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
'400': {
|
||
description: 'Bad request',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
$ref: '#/components/schemas/Error'
|
||
},
|
||
example: {
|
||
success: false,
|
||
error: 'Invalid tags format'
|
||
}
|
||
}
|
||
}
|
||
},
|
||
'500': {
|
||
description: 'Server error',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
$ref: '#/components/schemas/Error'
|
||
},
|
||
example: {
|
||
success: false,
|
||
error: 'Internal server 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',
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
'/events/tags': {
|
||
get: {
|
||
tags: ['events'],
|
||
summary: '获取标签列表',
|
||
description: '获取所有事件中的唯一标签列表。如果提供了 teamId，则只返回该团队的标签。',
|
||
parameters: [
|
||
{
|
||
name: 'teamId',
|
||
in: 'query',
|
||
required: false,
|
||
schema: {
|
||
type: 'string',
|
||
},
|
||
description: '团队ID（可选）。如果提供，则只返回该团队的标签。',
|
||
},
|
||
],
|
||
responses: {
|
||
'200': {
|
||
description: '成功获取标签列表',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: {
|
||
type: 'boolean',
|
||
example: true,
|
||
},
|
||
data: {
|
||
type: 'array',
|
||
items: {
|
||
type: 'object',
|
||
properties: {
|
||
tag_name: {
|
||
type: 'string',
|
||
example: 'marketing',
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
'500': {
|
||
description: '服务器错误',
|
||
content: {
|
||
'application/json': {
|
||
schema: {
|
||
type: 'object',
|
||
properties: {
|
||
success: {
|
||
type: 'boolean',
|
||
example: false,
|
||
},
|
||
error: {
|
||
type: 'string',
|
||
example: 'Failed to fetch tags',
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
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 (
|
||
<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>
|
||
);
|
||
}
|