vitalitymailg/shorturl-analytics
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

swagger configure

Browse Source
This commit is contained in:
William Tso
2025-03-26 17:17:47 +08:00
parent e916eab92c
commit 913c9cd289
4 changed files with 2800 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

518
app/(swagger)/swagger/page.tsx Normal file
View File

@@ -0,0 +1,518 @@
"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: {
summary: 'Get time series data',
parameters: [
{
name: 'startTime',
in: 'query',
required: true,
schema: {
type: 'string',
format: 'date-time',
},
},
{
name: 'endTime',
in: 'query',
required: true,
schema: {
type: 'string',
format: 'date-time',
},
},
],
responses: {
'200': {
description: 'Successful response',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
data: {
type: 'array',
items: {
$ref: '#/components/schemas/TimeSeriesData',
},
},
},
},
},
},
},
},
},
},
'/events/geo': {
get: {
summary: 'Get geographic data',
parameters: [
{
name: 'startTime',
in: 'query',
required: true,
schema: {
type: 'string',
format: 'date-time',
},
},
{
name: 'endTime',
in: 'query',
required: true,
schema: {
type: 'string',
format: 'date-time',
},
},
],
responses: {
'200': {
description: 'Successful response',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
data: {
type: 'array',
items: {
$ref: '#/components/schemas/GeoData',
},
},
},
},
},
},
},
},
},
},
'/events/devices': {
get: {
summary: 'Get device analytics data',
parameters: [
{
name: 'startTime',
in: 'query',
required: true,
schema: {
type: 'string',
format: 'date-time',
},
},
{
name: 'endTime',
in: 'query',
required: true,
schema: {
type: 'string',
format: 'date-time',
},
},
],
responses: {
'200': {
description: 'Successful response',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
data: {
$ref: '#/components/schemas/DeviceAnalytics',
},
},
},
},
},
},
},
},
},
},
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' },
events: { type: 'number' },
visitors: { type: 'number' },
conversions: { type: 'number' },
},
},
GeoData: {
type: 'object',
properties: {
location: { type: 'string' },
country: { type: 'string' },
region: { type: 'string' },
city: { type: 'string' },
visits: { type: 'number' },
visitors: { type: 'number' },
percentage: { type: 'number' },
},
},
DeviceAnalytics: {
type: 'object',
properties: {
deviceTypes: {
type: 'array',
items: {
type: 'object',
properties: {
type: { type: 'string' },
count: { type: 'number' },
percentage: { type: 'number' },
},
},
},
browsers: {
type: 'array',
items: {
type: 'object',
properties: {
name: { type: 'string' },
count: { type: 'number' },
percentage: { type: 'number' },
},
},
},
operatingSystems: {
type: 'array',
items: {
type: 'object',
properties: {
name: { type: 'string' },
count: { type: 'number' },
percentage: { type: 'number' },
},
},
},
},
},
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>
);
}

13
next.config.js Normal file
View File

@@ -0,0 +1,13 @@
/** @type {import('next').NextConfig} */
const nextConfig = {
transpilePackages: ['swagger-ui-react'],
webpack: (config) => {
config.module.rules.push({
test: /\.css$/,
use: ['style-loader', 'css-loader'],
});
return config;
},
};
module.exports = nextConfig;

7
package.json
View File

@@ -33,6 +33,8 @@
"react": "^19.0.0", "react": "^19.0.0",
"react-dom": "^19.0.0", "react-dom": "^19.0.0",
"recharts": "^2.15.1", "recharts": "^2.15.1",
"swagger-ui-dist": "^5.12.0",
"swagger-ui-react": "^5.12.0",
"uuid": "^10.0.0" "uuid": "^10.0.0"
}, },
"devDependencies": { "devDependencies": {
@@ -41,10 +43,13 @@
"@types/node": "^20", "@types/node": "^20",
"@types/react": "^19", "@types/react": "^19",
"@types/react-dom": "^19", "@types/react-dom": "^19",
"@types/swagger-ui-react": "^4.18.3",
"css-loader": "^7.1.2",
"eslint": "^9", "eslint": "^9",
"eslint-config-next": "15.2.3", "eslint-config-next": "15.2.3",
"style-loader": "^4.0.0",
"tailwindcss": "^4", "tailwindcss": "^4",
"typescript": "^5" "typescript": "^5"
}, },
"packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0" "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
} }

2263
pnpm-lock.yaml generated
View File

File diff suppressed because it is too large Load Diff