Skip to content

13. Create API Documentation System #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yorliabdulai wants to merge 1 commit into
base: main
Choose a base branch
from
Open

13. Create API Documentation System #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6,616 changes: 5,549 additions & 1,067 deletions backend/package-lock.json
View file
Open in desktop

Large diffs are not rendered by default.

22 changes: 15 additions & 7 deletions backend/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,22 +14,30 @@
"test:unit": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --testPathIgnorePatterns=integration",
"test:setup": "node -e \"console.log('To set up testing, see tests/QUICK_START.md')\""
},
"keywords": ["wikipedia", "verification", "api", "express", "mongodb"],
"keywords": [
"wikipedia",
"verification",
"api",
"express",
"mongodb"
],
"author": "",
"license": "MIT",
"dependencies": {
"express": "^4.18.2",
"mongoose": "^8.0.3",
"bcryptjs": "^2.4.3",
"jsonwebtoken": "^9.0.2",
"cookie-parser": "^1.4.6",
"cors": "^2.8.5",
"dotenv": "^16.3.1",
"express": "^4.18.2",
"express-rate-limit": "^7.1.5",
"express-validator": "^7.0.1",
"helmet": "^7.1.0",
"express-rate-limit": "^7.1.5",
"jsonwebtoken": "^9.0.2",
"mongoose": "^8.0.3",
"morgan": "^1.10.0",
"cookie-parser": "^1.4.6",
"multer": "^1.4.5-lts.1"
"multer": "^1.4.5-lts.1",
"swagger-jsdoc": "^6.2.8",
"swagger-ui-express": "^5.0.1"
},
"devDependencies": {
"@jest/globals": "^30.2.0",
Expand Down
314 changes: 314 additions & 0 deletions backend/src/config/swagger.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,314 @@
import swaggerJsdoc from 'swagger-jsdoc';

const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'WikiSource Verifier API',
version: '1.0.0',
description: 'Comprehensive API documentation for the WikiSource Verifier platform - a system for verifying and managing Wikipedia source submissions',
contact: {
name: 'API Support',
email: 'support@wikisource-verifier.com'
},
license: {
name: 'MIT',
url: 'https://opensource.org/licenses/MIT'
}
},
servers: [
{
url: 'http://localhost:5000',
description: 'Development server'
},
{
url: 'https://api.wikisource-verifier.com',
description: 'Production server'
}
],
components: {
securitySchemes: {
bearerAuth: {
type: 'http',
scheme: 'bearer',
bearerFormat: 'JWT',
description: 'Enter JWT token obtained from login or register endpoint'
},
cookieAuth: {
type: 'apiKey',
in: 'cookie',
name: 'token',
description: 'JWT token stored in HTTP-only cookie'
}
},
schemas: {
User: {
type: 'object',
properties: {
_id: {
type: 'string',
description: 'User ID'
},
username: {
type: 'string',
description: 'Username',
example: 'johndoe'
},
email: {
type: 'string',
format: 'email',
description: 'User email address',
example: 'john@example.com'
},
country: {
type: 'string',
description: 'User country',
example: 'US'
},
role: {
type: 'string',
enum: ['contributor', 'verifier', 'admin'],
description: 'User role',
example: 'contributor'
},
points: {
type: 'number',
description: 'User points',
example: 150
},
badges: {
type: 'array',
items: {
type: 'object',
properties: {
name: {
type: 'string',
example: 'First Contribution'
},
icon: {
type: 'string',
example: 'star'
},
earnedAt: {
type: 'string',
format: 'date-time'
}
}
}
},
isActive: {
type: 'boolean',
description: 'Whether the user account is active',
example: true
},
createdAt: {
type: 'string',
format: 'date-time'
},
updatedAt: {
type: 'string',
format: 'date-time'
}
}
},
Submission: {
type: 'object',
properties: {
_id: {
type: 'string',
description: 'Submission ID'
},
title: {
type: 'string',
description: 'Wikipedia article title',
example: 'Artificial Intelligence'
},
url: {
type: 'string',
format: 'uri',
description: 'Wikipedia article URL',
example: 'https://en.wikipedia.org/wiki/Artificial_intelligence'
},
country: {
type: 'string',
description: 'Country code',
example: 'US'
},
status: {
type: 'string',
enum: ['pending', 'verified', 'rejected'],
description: 'Submission status',
example: 'pending'
},
submittedBy: {
type: 'string',
description: 'User ID of submitter'
},
verifiedBy: {
type: 'string',
description: 'User ID of verifier',
nullable: true
},
verificationNotes: {
type: 'string',
description: 'Notes from verifier',
nullable: true
},
createdAt: {
type: 'string',
format: 'date-time'
},
updatedAt: {
type: 'string',
format: 'date-time'
}
}
},
Error: {
type: 'object',
properties: {
success: {
type: 'boolean',
example: false
},
message: {
type: 'string',
example: 'Error message'
},
errors: {
type: 'array',
items: {
type: 'object',
properties: {
field: {
type: 'string'
},
message: {
type: 'string'
}
}
}
}
}
},
Success: {
type: 'object',
properties: {
success: {
type: 'boolean',
example: true
},
message: {
type: 'string',
example: 'Operation successful'
},
data: {
type: 'object',
description: 'Response data'
}
}
}
},
responses: {
UnauthorizedError: {
description: 'Authentication required or invalid token',
content: {
'application/json': {
schema: {
$ref: '#/components/schemas/Error'
},
example: {
success: false,
message: 'Not authorized to access this route'
}
}
}
},
ForbiddenError: {
description: 'Insufficient permissions',
content: {
'application/json': {
schema: {
$ref: '#/components/schemas/Error'
},
example: {
success: false,
message: 'Access forbidden. Admin role required.'
}
}
}
},
NotFoundError: {
description: 'Resource not found',
content: {
'application/json': {
schema: {
$ref: '#/components/schemas/Error'
},
example: {
success: false,
message: 'Resource not found'
}
}
}
},
ValidationError: {
description: 'Validation error',
content: {
'application/json': {
schema: {
$ref: '#/components/schemas/Error'
},
example: {
success: false,
message: 'Validation failed',
errors: [
{
field: 'email',
message: 'Please provide a valid email'
}
]
}
}
}
}
}
},
tags: [
{
name: 'Authentication',
description: 'User authentication and authorization endpoints'
},
{
name: 'Submissions',
description: 'Wikipedia source submission management'
},
{
name: 'Users',
description: 'User profile and management endpoints'
},
{
name: 'Admin',
description: 'Administrative operations (Admin only)'
},
{
name: 'Countries',
description: 'Country statistics and management'
},
{
name: 'System',
description: 'System health and maintenance (Admin only)'
},
{
name: 'Reports',
description: 'Analytics and reporting (Admin/Verifier only)'
}
]
},
apis: ['./src/routes/*.js', './src/server.js'] // Paths to files containing OpenAPI definitions
};

const swaggerSpec = swaggerJsdoc(options);

export default swaggerSpec;

Loading