OpenAPI / Swagger
Purpose
This page documents the current OpenAPI / Swagger status for the Maqsafy backend APIs.
Current Status
| Item | Status | Notes |
|---|---|---|
| Postman API documentation | Confirmed | Technical team confirmed current API documentation exists in Postman |
| OpenAPI specification file | Draft Available | Generated from the documented Laravel route inventory |
| Swagger UI | Optional / Pending Decision | Can be opened by importing the OpenAPI file into Swagger Editor or Swagger UI if a hosted UI is required |
| Runtime route validation | Needs Technical Verification | Validate against php artisan route:list when the backend can run under the compatible PHP version |
| Request / response schemas | Partial | Common schemas are documented; endpoint-specific payloads need backend review |
| Authentication scheme | Draft Available | Bearer token scheme documented based on protected API behavior |
OpenAPI File
The draft specification is available here:
How To Review In Swagger
- Open Swagger Editor or Swagger UI.
- Import the
openapi.yamlfile from this documentation site. - Validate paths, methods, authentication, request bodies, responses, and error codes with the backend team.
- Replace placeholder or generic schemas with confirmed backend payloads.
Included Endpoint Areas
| Area | Status |
|---|---|
| Authentication | Draft Available |
| User profile | Draft Available |
| Students | Draft Available |
| Orders | Draft Available |
| Products | Draft Available |
| Supplier stores and supplier orders | Draft Available |
| Wallet search | Draft Available |
| Payments / Apple Pay | Draft Available |
| Notifications | Draft Available |
| Public content and contact requests | Draft Available |
Validation Requirements
Before this OpenAPI file is marked as final, the technical team should confirm:
- The real API base URL and version prefix.
- All protected routes and middleware.
- Exact request body fields.
- Exact response payloads.
- Error response format.
- Idempotency behavior for payment-related endpoints.
- Whether a hosted Swagger UI is required in addition to the confirmed Postman documentation.
Review Decision
| Decision | Status |
|---|---|
| OpenAPI draft exists | Confirmed |
| Postman documentation exists | Confirmed |
| Swagger UI hosted by Maqsafy | Optional / Pending Decision |
| Final API contract approved | Needs Technical Verification |