recreate project
This commit is contained in:
root
@@ -0,0 +1,451 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: Administrator API - Al Rahma Sunday School
|
||||
version: 1.0.0
|
||||
description: >
|
||||
REST API for administrator functionality. These endpoints mirror the admin view features
|
||||
but return JSON responses for API consumers.
|
||||
|
||||
All endpoints require JWT authentication using a Bearer token, unless otherwise noted.
|
||||
|
||||
Standard response format:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success|error",
|
||||
"message": "string",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
servers:
|
||||
- url: https://alrahmaisgl.org/api/v1
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
tags:
|
||||
- name: Admin Dashboard
|
||||
description: Summary metrics for admins
|
||||
- name: Absence
|
||||
description: Admin absence/time-off self-service
|
||||
- name: Search
|
||||
description: Tokenized search across users, students, parents, staff and emergency contacts
|
||||
- name: Enrollment
|
||||
description: Enrollment/withdrawal data and status updates
|
||||
- name: Profiles
|
||||
description: Aggregate student and parent profiles for administrator views
|
||||
|
||||
paths:
|
||||
/administrator/dashboard:
|
||||
get:
|
||||
tags: [Admin Dashboard]
|
||||
summary: Get dashboard metrics
|
||||
security:
|
||||
- BearerAuth: []
|
||||
responses:
|
||||
200:
|
||||
description: Metrics retrieved
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AdminDashboardResponse'
|
||||
401:
|
||||
description: Unauthorized
|
||||
|
||||
/administrator/absence:
|
||||
get:
|
||||
tags: [Absence]
|
||||
summary: Get admin absence info and allowed dates
|
||||
security:
|
||||
- BearerAuth: []
|
||||
responses:
|
||||
200:
|
||||
description: Absence info
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AbsenceInfoResponse'
|
||||
post:
|
||||
tags: [Absence]
|
||||
summary: Submit absence days for current admin
|
||||
security:
|
||||
- BearerAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SubmitAbsenceRequest'
|
||||
responses:
|
||||
200:
|
||||
description: Absence saved
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SubmitAbsenceResponse'
|
||||
422:
|
||||
description: Validation error
|
||||
|
||||
/administrator/search:
|
||||
get:
|
||||
tags: [Search]
|
||||
summary: Tokenized search across entities
|
||||
description: >
|
||||
Splits the query into tokens and matches them across multiple columns; phone-like tokens
|
||||
also match common US formats.
|
||||
security:
|
||||
- BearerAuth: []
|
||||
parameters:
|
||||
- name: q
|
||||
in: query
|
||||
required: true
|
||||
schema: { type: string, example: "ahmed 4105551234" }
|
||||
responses:
|
||||
200:
|
||||
description: Search results
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SearchResponse'
|
||||
|
||||
/administrator/enrollment-withdrawal/data:
|
||||
get:
|
||||
tags: [Enrollment]
|
||||
summary: Data for the Enrollment/Withdrawal admin page
|
||||
security:
|
||||
- BearerAuth: []
|
||||
parameters:
|
||||
- name: schoolYear
|
||||
in: query
|
||||
schema: { type: string, example: "2024-2025" }
|
||||
responses:
|
||||
200:
|
||||
description: Data payload for UI
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/EnrollmentWithdrawalDataResponse'
|
||||
|
||||
/administrator/enrollment-withdrawal/update:
|
||||
post:
|
||||
tags: [Enrollment]
|
||||
summary: Batch update enrollment statuses
|
||||
description: >
|
||||
Updates students' enrollment statuses and computes refunds when applicable.
|
||||
security:
|
||||
- BearerAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UpdateEnrollmentStatusesRequest'
|
||||
responses:
|
||||
200:
|
||||
description: Update results
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UpdateEnrollmentStatusesResponse'
|
||||
422:
|
||||
description: Validation error
|
||||
|
||||
/administrator/students:
|
||||
get:
|
||||
tags: [Profiles]
|
||||
summary: Aggregated student profiles
|
||||
security:
|
||||
- BearerAuth: []
|
||||
responses:
|
||||
200:
|
||||
description: Student profiles
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/StudentProfilesResponse'
|
||||
|
||||
/administrator/parents:
|
||||
get:
|
||||
tags: [Profiles]
|
||||
summary: Parent profiles with recent invoice balances
|
||||
security:
|
||||
- BearerAuth: []
|
||||
responses:
|
||||
200:
|
||||
description: Parent profiles
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ParentProfilesResponse'
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: >
|
||||
Include your token in the Authorization header.
|
||||
Example:
|
||||
```
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
|
||||
```
|
||||
|
||||
schemas:
|
||||
BasicSuccess:
|
||||
type: object
|
||||
properties:
|
||||
status: { type: string, example: "success" }
|
||||
message: { type: string }
|
||||
data: { nullable: true }
|
||||
|
||||
AdminDashboardResponse:
|
||||
type: object
|
||||
properties:
|
||||
status: { type: string, example: "success" }
|
||||
message: { type: string }
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
counts:
|
||||
type: object
|
||||
properties:
|
||||
students: { type: integer, example: 240 }
|
||||
teachers: { type: integer, example: 36 }
|
||||
teacherAssistants: { type: integer, example: 12 }
|
||||
admins: { type: integer, example: 5 }
|
||||
parents: { type: integer, example: 180 }
|
||||
recentActivities:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
login_time: { type: string, format: date-time }
|
||||
email: { type: string, format: email }
|
||||
meta:
|
||||
type: object
|
||||
properties:
|
||||
schoolYear: { type: string, example: "2024-2025" }
|
||||
semester: { type: string, example: "Fall" }
|
||||
|
||||
AbsenceInfoResponse:
|
||||
type: object
|
||||
properties:
|
||||
status: { type: string, example: "success" }
|
||||
message: { type: string }
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
admin_name: { type: string }
|
||||
semester: { type: string }
|
||||
school_year: { type: string }
|
||||
existing:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id: { type: integer }
|
||||
user_id: { type: integer }
|
||||
date: { type: string, format: date }
|
||||
status: { type: string, enum: [present, absent, late] }
|
||||
reason: { type: string, nullable: true }
|
||||
semester: { type: string }
|
||||
school_year: { type: string }
|
||||
available_dates:
|
||||
type: array
|
||||
items: { type: string, format: date }
|
||||
|
||||
SubmitAbsenceRequest:
|
||||
type: object
|
||||
required: [dates, reason]
|
||||
properties:
|
||||
dates:
|
||||
type: array
|
||||
items: { type: string, format: date }
|
||||
example: ["2025-09-14", "2025-10-05"]
|
||||
reason_type:
|
||||
type: string
|
||||
example: vacation
|
||||
reason:
|
||||
type: string
|
||||
example: Visiting family
|
||||
|
||||
SubmitAbsenceResponse:
|
||||
type: object
|
||||
properties:
|
||||
status: { type: string, example: "success" }
|
||||
message: { type: string }
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
saved: { type: integer, example: 2 }
|
||||
invalid:
|
||||
type: array
|
||||
items: { type: string, format: date }
|
||||
saved_dates:
|
||||
type: array
|
||||
items: { type: string, format: date }
|
||||
|
||||
SearchResponse:
|
||||
type: object
|
||||
properties:
|
||||
status: { type: string, example: "success" }
|
||||
message: { type: string }
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
users:
|
||||
type: array
|
||||
items: { type: object, additionalProperties: true }
|
||||
students:
|
||||
type: array
|
||||
items: { type: object, additionalProperties: true }
|
||||
parents:
|
||||
type: array
|
||||
items: { type: object, additionalProperties: true }
|
||||
staff:
|
||||
type: array
|
||||
items: { type: object, additionalProperties: true }
|
||||
emergency_contacts:
|
||||
type: array
|
||||
items: { type: object, additionalProperties: true }
|
||||
total: { type: integer }
|
||||
|
||||
EnrollmentWithdrawalDataResponse:
|
||||
type: object
|
||||
properties:
|
||||
status: { type: string, example: "success" }
|
||||
message: { type: string }
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
students:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
properties:
|
||||
id: { type: integer }
|
||||
student_id: { type: integer }
|
||||
parent_id: { type: integer }
|
||||
parent_label: { type: string }
|
||||
enrollment_status: { type: string }
|
||||
class_section: { type: string }
|
||||
is_new: { type: integer, example: 0 }
|
||||
new_student: { type: string, example: "No" }
|
||||
registration_date_order: { type: string, example: "2025-09-01" }
|
||||
classes:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id: { type: integer }
|
||||
class_section_id: { type: integer }
|
||||
class_section_name: { type: string }
|
||||
school_year: { type: string, nullable: true }
|
||||
semester: { type: string, nullable: true }
|
||||
semester: { type: string }
|
||||
school_year: { type: string }
|
||||
schoolYears:
|
||||
type: array
|
||||
items: { type: string }
|
||||
|
||||
UpdateEnrollmentStatusesRequest:
|
||||
type: object
|
||||
required: [enrollment_status]
|
||||
properties:
|
||||
enrollment_status:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
enum: [
|
||||
"admission under review",
|
||||
"payment pending",
|
||||
"enrolled",
|
||||
"withdraw under review",
|
||||
"refund pending",
|
||||
"withdrawn",
|
||||
"denied",
|
||||
"waitlist"
|
||||
]
|
||||
example:
|
||||
"101": "payment pending"
|
||||
"102": "enrolled"
|
||||
|
||||
UpdateEnrollmentStatusesResponse:
|
||||
type: object
|
||||
properties:
|
||||
status: { type: string, example: "success" }
|
||||
message: { type: string }
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
errors:
|
||||
type: array
|
||||
items: { type: string }
|
||||
groupsByParentStatus:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
student_id: { type: integer }
|
||||
student_name: { type: string }
|
||||
|
||||
StudentProfilesResponse:
|
||||
type: object
|
||||
properties:
|
||||
status: { type: string, example: "success" }
|
||||
message: { type: string }
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
students:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
properties:
|
||||
id: { type: integer }
|
||||
firstname: { type: string }
|
||||
lastname: { type: string }
|
||||
parent_firstname: { type: string }
|
||||
parent_lastname: { type: string }
|
||||
parent_email: { type: string, format: email }
|
||||
parent_phone: { type: string }
|
||||
emergency_name: { type: string, nullable: true }
|
||||
emergency_relationship: { type: string, nullable: true }
|
||||
emergency_phone: { type: string, nullable: true }
|
||||
allergies: { type: string, nullable: true }
|
||||
medical_conditions: { type: string, nullable: true }
|
||||
class_section_name: { type: string }
|
||||
|
||||
ParentProfilesResponse:
|
||||
type: object
|
||||
properties:
|
||||
status: { type: string, example: "success" }
|
||||
message: { type: string }
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
parents:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id: { type: integer }
|
||||
school_id: { type: string }
|
||||
firstname: { type: string }
|
||||
lastname: { type: string }
|
||||
email: { type: string, format: email }
|
||||
cellphone: { type: string }
|
||||
gender: { type: string, nullable: true }
|
||||
created_at: { type: string, format: date-time }
|
||||
school_year: { type: string }
|
||||
paid_amount: { type: number }
|
||||
balance: { type: number }
|
||||
|
||||
Reference in New Issue
Block a user