swagger configure
This commit is contained in:
518
app/(swagger)/swagger/page.tsx
Normal file
518
app/(swagger)/swagger/page.tsx
Normal 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
13
next.config.js
Normal 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;
|
||||
@@ -33,6 +33,8 @@
|
||||
"react": "^19.0.0",
|
||||
"react-dom": "^19.0.0",
|
||||
"recharts": "^2.15.1",
|
||||
"swagger-ui-dist": "^5.12.0",
|
||||
"swagger-ui-react": "^5.12.0",
|
||||
"uuid": "^10.0.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
@@ -41,10 +43,13 @@
|
||||
"@types/node": "^20",
|
||||
"@types/react": "^19",
|
||||
"@types/react-dom": "^19",
|
||||
"@types/swagger-ui-react": "^4.18.3",
|
||||
"css-loader": "^7.1.2",
|
||||
"eslint": "^9",
|
||||
"eslint-config-next": "15.2.3",
|
||||
"style-loader": "^4.0.0",
|
||||
"tailwindcss": "^4",
|
||||
"typescript": "^5"
|
||||
},
|
||||
"packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
|
||||
}
|
||||
}
|
||||
2263
pnpm-lock.yaml
generated
2263
pnpm-lock.yaml
generated
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user