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

swagerr doc

Browse Source
This commit is contained in:
William Tso
2025-03-26 17:39:58 +08:00
parent 913c9cd289
commit ca8a7d56f1
2 changed files with 274 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
app/(swagger)/swagger/page.tsx
View File

@@ -175,7 +175,9 @@ export default function SwaggerPage() {
},
'/events/time-series': {
get: {
tags: ['events'],
summary: 'Get time series data',
description: 'Get time-based analytics data for events',
parameters: [
{
name: 'startTime',
@@ -185,6 +187,7 @@ export default function SwaggerPage() {
type: 'string',
format: 'date-time',
},
description: 'Start time for time series data (ISO 8601 format)',
},
{
name: 'endTime',
@@ -194,6 +197,7 @@ export default function SwaggerPage() {
type: 'string',
format: 'date-time',
},
description: 'End time for time series data (ISO 8601 format)',
},
],
responses: {
@@ -215,12 +219,24 @@ export default function SwaggerPage() {
},
},
},
'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',
@@ -230,6 +246,7 @@ export default function SwaggerPage() {
type: 'string',
format: 'date-time',
},
description: 'Start time for geographic data (ISO 8601 format)',
},
{
name: 'endTime',
@@ -239,6 +256,7 @@ export default function SwaggerPage() {
type: 'string',
format: 'date-time',
},
description: 'End time for geographic data (ISO 8601 format)',
},
],
responses: {
@@ -260,12 +278,24 @@ export default function SwaggerPage() {
},
},
},
'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',
@@ -275,6 +305,7 @@ export default function SwaggerPage() {
type: 'string',
format: 'date-time',
},
description: 'Start time for device analytics (ISO 8601 format)',
},
{
name: 'endTime',
@@ -284,6 +315,7 @@ export default function SwaggerPage() {
type: 'string',
format: 'date-time',
},
description: 'End time for device analytics (ISO 8601 format)',
},
],
responses: {
@@ -302,6 +334,16 @@ export default function SwaggerPage() {
},
},
},
'400': {
description: 'Bad request',
content: {
'application/json': {
schema: {
$ref: '#/components/schemas/Error',
},
},
},
},
},
},
},
@@ -408,22 +450,56 @@ export default function SwaggerPage() {
TimeSeriesData: {
type: 'object',
properties: {
timestamp: { type: 'string', format: 'date-time' },
events: { type: 'number' },
visitors: { type: 'number' },
conversions: { type: 'number' },
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' },
country: { type: 'string' },
region: { type: 'string' },
city: { type: 'string' },
visits: { type: 'number' },
visitors: { type: 'number' },
percentage: { type: 'number' },
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: {
@@ -434,9 +510,18 @@ export default function SwaggerPage() {
items: {
type: 'object',
properties: {
type: { type: 'string' },
count: { type: 'number' },
percentage: { type: 'number' },
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',
},
},
},
},
@@ -445,9 +530,18 @@ export default function SwaggerPage() {
items: {
type: 'object',
properties: {
name: { type: 'string' },
count: { type: 'number' },
percentage: { type: 'number' },
name: {
type: 'string',
description: 'Browser name',
},
count: {
type: 'number',
description: 'Number of visits from this browser',
},
percentage: {
type: 'number',
description: 'Percentage of total visits',
},
},
},
},
@@ -456,9 +550,18 @@ export default function SwaggerPage() {
items: {
type: 'object',
properties: {
name: { type: 'string' },
count: { type: 'number' },
percentage: { type: 'number' },
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',
},
},
},
},

151
docs/swagger-setup.md Normal file
View File

@@ -0,0 +1,151 @@
# Setting up Swagger UI in Next.js
This guide explains how to set up Swagger UI in a Next.js application using route groups.
## Directory Structure
The recommended directory structure for Swagger documentation:
```
app/
(swagger)/ # Route group for swagger-related pages
swagger/ # Actual swagger route
page.tsx # Swagger UI component
```
## Installation
1. Add Swagger UI dependencies to your project:
```json
{
"dependencies": {
"swagger-ui-react": "^5.12.0",
"swagger-ui-dist": "^5.12.0"
},
"devDependencies": {
"@types/swagger-ui-react": "^4.18.3"
}
}
```
2. Install webpack style loaders for handling Swagger UI CSS:
```bash
pnpm add -D style-loader css-loader
```
## Next.js Configuration
Create or update `next.config.js` to handle Swagger UI CSS:
```javascript
/** @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;
```
## Swagger UI Component
Create `app/(swagger)/swagger/page.tsx`:
```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';
}, []);
const swaggerConfig = {
openapi: '3.0.0',
info: {
title: 'Your API Title',
version: '1.0.0',
description: 'API documentation',
contact: {
name: 'API Support',
email: 'support@example.com',
},
license: {
name: 'MIT',
url: 'https://opensource.org/licenses/MIT',
},
},
// ... your API configuration
};
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 API endpoints using the interactive documentation below.
</p>
</div>
<SwaggerUI spec={swaggerConfig} />
</div>
);
}
```
## Best Practices
1. **Route Groups**: Use route groups `(groupname)` to organize related pages without affecting the URL structure.
2. **API Documentation**:
- Add detailed descriptions for all endpoints
- Include parameter descriptions and constraints
- Define response schemas
- Document error responses
- Use appropriate data formats (UUID, URI, etc.)
- Group related endpoints using tags
3. **Swagger Configuration**:
- Add contact information
- Include license details
- Set appropriate servers configuration
- Define required fields
- Add parameter validations (min/max values)
## Common Issues
1. **Route Conflicts**: Avoid parallel routes that resolve to the same path. For example, don't have both `app/swagger/page.tsx` and `app/(group)/swagger/page.tsx` as they would conflict.
2. **CSS Loading**: Make sure to:
- Import Swagger UI CSS
- Configure webpack in `next.config.js`
- Use the `"use client"` directive as Swagger UI is a client-side component
3. **React Version Compatibility**: Be aware of potential peer dependency warnings between Swagger UI React and your React version. You might need to use `--legacy-peer-deps` or adjust your React version accordingly.
## Accessing the Documentation
After setup, your Swagger documentation will be available at `/swagger` in your application. The UI provides:
- Interactive API documentation
- Request/response examples
- Try-it-out functionality
- Schema definitions
- Error responses
## Maintenance
Keep your Swagger documentation up-to-date by:
- Updating the OpenAPI specification when adding or modifying endpoints
- Maintaining accurate parameter descriptions
- Keeping example values relevant
- Updating response schemas when data structures change