"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: { 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: { 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.

); }