621 lines
18 KiB
TypeScript
621 lines
18 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': {
|
|
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 (
|
|
<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>
|
|
);
|
|
}
|