1 line
22 KiB
JSON
1 line
22 KiB
JSON
{"openapi":"3.0.0","paths":{"/api":{"get":{"operationId":"AppController_getHello","parameters":[],"responses":{"200":{"description":"API is running"}},"summary":"Health check endpoint","tags":["Health"]}},"/api/health":{"get":{"operationId":"AppController_getHealth","parameters":[],"responses":{"200":{"description":"API health status"}},"summary":"Health check endpoint","tags":["Health"]}},"/api/auth/register":{"post":{"operationId":"AuthController_register","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterDto"}}}},"responses":{"201":{"description":"User successfully registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponseDto"}}}},"400":{"description":"Bad request - validation failed"},"409":{"description":"Conflict - email already registered"}},"summary":"Register a new user","tags":["Authentication"]}},"/api/auth/login":{"post":{"operationId":"AuthController_login","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginDto"}}}},"responses":{"200":{"description":"User successfully logged in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponseDto"}}}},"401":{"description":"Unauthorized - invalid credentials"}},"summary":"Login user","tags":["Authentication"]}},"/api/auth/profile":{"get":{"operationId":"AuthController_getProfile","parameters":[],"responses":{"200":{"description":"User profile retrieved successfully"},"401":{"description":"Unauthorized - invalid or missing token"}},"security":[{"bearer":[]}],"summary":"Get current user profile","tags":["Authentication"]}},"/api/auth/refresh":{"post":{"description":"Exchanges a valid refresh token for a new access token and refresh token. Implements token rotation - the old refresh token will be invalidated.","operationId":"AuthController_refreshToken","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenDto"}}}},"responses":{"200":{"description":"Token refreshed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponseDto"}}}},"401":{"description":"Unauthorized - invalid, expired, or revoked refresh token"}},"summary":"Refresh access token using refresh token","tags":["Authentication"]}},"/api/auth/logout":{"post":{"description":"Revokes the refresh token to prevent future token refreshes","operationId":"AuthController_logout","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenDto"}}}},"responses":{"200":{"description":"Logged out successfully"},"400":{"description":"Bad request - refresh token is required"}},"summary":"Logout user","tags":["Authentication"]}},"/api/auth/revoke-all":{"post":{"description":"Revokes all refresh tokens for the authenticated user. Useful for security purposes or when logging out from all devices.","operationId":"AuthController_revokeAllTokens","parameters":[],"responses":{"200":{"description":"All tokens revoked successfully"},"401":{"description":"Unauthorized - invalid or missing access token"}},"security":[{"bearer":[]}],"summary":"Revoke all refresh tokens for current user","tags":["Authentication"]}},"/api/users":{"post":{"operationId":"UsersController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserDto"}}}},"responses":{"201":{"description":"User successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Admin role required"},"409":{"description":"Email already exists"}},"security":[{"bearer":[]}],"summary":"Create new user (Admin only)","tags":["Users"]},"get":{"operationId":"UsersController_findAll","parameters":[],"responses":{"200":{"description":"List of users","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserResponseDto"}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Insufficient permissions"}},"security":[{"bearer":[]}],"summary":"Get all users (Admin/Manager only)","tags":["Users"]}},"/api/users/{id}":{"get":{"operationId":"UsersController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"User found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Insufficient permissions"},"404":{"description":"User not found"}},"security":[{"bearer":[]}],"summary":"Get user by ID (Admin/Manager only)","tags":["Users"]},"patch":{"operationId":"UsersController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserDto"}}}},"responses":{"200":{"description":"User successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Admin role required"},"404":{"description":"User not found"},"409":{"description":"Email already exists"}},"security":[{"bearer":[]}],"summary":"Update user (Admin only)","tags":["Users"]},"delete":{"operationId":"UsersController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"User successfully deleted"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Admin role required"},"404":{"description":"User not found"}},"security":[{"bearer":[]}],"summary":"Delete user (Admin only)","tags":["Users"]}},"/api/products":{"get":{"operationId":"ProductsController_findAll","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"categoryId","required":false,"in":"query","description":"Filter by category ID","schema":{"example":"123e4567-e89b-12d3-a456-426614174000","type":"string"}},{"name":"search","required":false,"in":"query","description":"Search query for product name or description","schema":{"example":"laptop","type":"string"}},{"name":"minPrice","required":false,"in":"query","description":"Minimum price filter","schema":{"minimum":0,"example":100,"type":"number"}},{"name":"maxPrice","required":false,"in":"query","description":"Maximum price filter","schema":{"minimum":0,"example":1000,"type":"number"}},{"name":"isAvailable","required":false,"in":"query","description":"Filter by availability status","schema":{"example":true,"type":"boolean"}}],"responses":{"200":{"description":"Products retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseDto"}}}},"500":{"description":"Internal server error"}},"summary":"Get all products with pagination and filters","tags":["products"]},"post":{"description":"Creates a new product and updates category product count","operationId":"ProductsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductDto"}}}},"responses":{"201":{"description":"Product created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseDto"}}}},"400":{"description":"Invalid input data"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient role"},"404":{"description":"Category not found"},"500":{"description":"Internal server error"}},"security":[{"bearer":[]}],"summary":"Create new product (Admin/Manager only)","tags":["products"]}},"/api/products/search":{"get":{"operationId":"ProductsController_search","parameters":[{"name":"q","required":true,"in":"query","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","schema":{"type":"number"}},{"name":"limit","required":true,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"Products found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseDto"}}}},"400":{"description":"Invalid search query"},"500":{"description":"Internal server error"}},"summary":"Search products by name or description","tags":["products"]}},"/api/products/category/{categoryId}":{"get":{"operationId":"ProductsController_findByCategory","parameters":[{"name":"categoryId","required":true,"in":"path","description":"Category UUID","schema":{"type":"string"}},{"name":"page","required":true,"in":"query","schema":{"type":"number"}},{"name":"limit","required":true,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"Products retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseDto"}}}},"404":{"description":"Category not found"},"500":{"description":"Internal server error"}},"summary":"Get products by category","tags":["products"]}},"/api/products/{id}":{"get":{"operationId":"ProductsController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"Product UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseDto"}}}},"404":{"description":"Product not found"},"500":{"description":"Internal server error"}},"summary":"Get single product by ID","tags":["products"]},"put":{"description":"Updates product details and handles category count if category changes","operationId":"ProductsController_update","parameters":[{"name":"id","required":true,"in":"path","description":"Product UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductDto"}}}},"responses":{"200":{"description":"Product updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseDto"}}}},"400":{"description":"Invalid input data"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - insufficient role"},"404":{"description":"Product or category not found"},"500":{"description":"Internal server error"}},"security":[{"bearer":[]}],"summary":"Update product (Admin/Manager only)","tags":["products"]},"delete":{"description":"Deletes product if not used in transactions, updates category count","operationId":"ProductsController_remove","parameters":[{"name":"id","required":true,"in":"path","description":"Product UUID","schema":{"type":"string"}}],"responses":{"204":{"description":"Product deleted successfully"},"400":{"description":"Cannot delete product used in transactions"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Admin only"},"404":{"description":"Product not found"},"500":{"description":"Internal server error"}},"security":[{"bearer":[]}],"summary":"Delete product (Admin only)","tags":["products"]}},"/api/categories":{"post":{"operationId":"CategoriesController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCategoryDto"}}}},"responses":{"201":{"description":"Category successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Admin or Manager role required"},"409":{"description":"Category name already exists"}},"security":[{"bearer":[]}],"summary":"Create new category (Admin/Manager only)","tags":["categories"]},"get":{"operationId":"CategoriesController_findAll","parameters":[],"responses":{"200":{"description":"List of all categories","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CategoryResponseDto"}}}}}},"summary":"Get all categories (Public)","tags":["categories"]}},"/api/categories/{id}":{"get":{"operationId":"CategoriesController_findOne","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryResponseDto"}}}},"404":{"description":"Category not found"}},"summary":"Get single category by ID (Public)","tags":["categories"]},"put":{"operationId":"CategoriesController_update","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCategoryDto"}}}},"responses":{"200":{"description":"Category successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryResponseDto"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Admin or Manager role required"},"404":{"description":"Category not found"},"409":{"description":"Category name already exists"}},"security":[{"bearer":[]}],"summary":"Update category (Admin/Manager only)","tags":["categories"]},"delete":{"description":"Delete category. Fails if category has products.","operationId":"CategoriesController_remove","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"Category successfully deleted"},"400":{"description":"Cannot delete category with products"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Admin role required"},"404":{"description":"Category not found"}},"security":[{"bearer":[]}],"summary":"Delete category (Admin only)","tags":["categories"]}},"/api/categories/{id}/products":{"get":{"description":"Returns category details along with associated products. Supports pagination.","operationId":"CategoriesController_findWithProducts","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}}],"responses":{"200":{"description":"Category with products"},"404":{"description":"Category not found"}},"summary":"Get category with its products (Public)","tags":["categories"]}}},"info":{"title":"Retail POS API","description":"RESTful API for Retail POS Flutter Application - Product Management, Transactions, and User Authentication","version":"1.0","contact":{"name":"API Support","url":"https://github.com/yourusername/retail-pos","email":"support@retailpos.com"}},"tags":[{"name":"Authentication","description":"User authentication and authorization"},{"name":"Users","description":"User management endpoints"},{"name":"Products","description":"Product management endpoints"},{"name":"Categories","description":"Category management endpoints"},{"name":"Transactions","description":"Transaction processing endpoints"},{"name":"Sync","description":"Offline sync management"}],"servers":[{"url":"http://localhost:3000","description":"Development"}],"components":{"securitySchemes":{"JWT":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Enter JWT token","name":"Authorization","in":"header"}},"schemas":{"RegisterDto":{"type":"object","properties":{"name":{"type":"string","example":"John Doe","description":"User full name","maxLength":255},"email":{"type":"string","example":"user@retailpos.com","description":"User email address (must be unique)"},"password":{"type":"string","example":"Password123!","description":"Password (min 8 chars, must contain uppercase, lowercase, and number)","minLength":8},"roles":{"type":"array","example":["user"],"description":"User roles","default":["user"],"items":{"type":"string","enum":["admin","manager","cashier","user"]}}},"required":["name","email","password"]},"UserResponseDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"roles":{"type":"array","items":{"type":"string","enum":["admin","manager","cashier","user"]}},"isActive":{"type":"boolean"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","email","roles","isActive","createdAt","updatedAt"]},"AuthResponseDto":{"type":"object","properties":{"access_token":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","description":"JWT access token"},"refresh_token":{"type":"string","example":"a1b2c3d4e5f6...","description":"Refresh token for obtaining new access tokens"},"user":{"$ref":"#/components/schemas/UserResponseDto"}},"required":["access_token","refresh_token","user"]},"LoginDto":{"type":"object","properties":{"email":{"type":"string","example":"admin@retailpos.com","description":"User email address"},"password":{"type":"string","example":"Admin123!","description":"User password (min 8 characters)","minLength":8}},"required":["email","password"]},"RefreshTokenDto":{"type":"object","properties":{"refreshToken":{"type":"string","example":"a1b2c3d4e5f6...","description":"Refresh token received during login"}},"required":["refreshToken"]},"CreateUserDto":{"type":"object","properties":{"name":{"type":"string","example":"John Doe","description":"User full name"},"email":{"type":"string","example":"user@retailpos.com","description":"User email address"},"password":{"type":"string","example":"Password123!","description":"User password"},"roles":{"type":"array","example":["user"],"items":{"type":"string","enum":["admin","manager","cashier","user"]}},"isActive":{"type":"boolean","example":true,"description":"User active status"}},"required":["name","email","password"]},"UpdateUserDto":{"type":"object","properties":{"name":{"type":"string","example":"John Doe","description":"User full name"},"email":{"type":"string","example":"user@retailpos.com","description":"User email address"},"roles":{"type":"array","example":["user"],"items":{"type":"string","enum":["admin","manager","cashier","user"]}},"isActive":{"type":"boolean","example":true,"description":"User active status"}}},"PaginationMetaDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Number of items per page"},"total":{"type":"number","description":"Total number of items"},"totalPages":{"type":"number","description":"Total number of pages"},"hasPreviousPage":{"type":"boolean","description":"Has previous page"},"hasNextPage":{"type":"boolean","description":"Has next page"}},"required":["page","limit","total","totalPages","hasPreviousPage","hasNextPage"]},"ApiResponseDto":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status"},"data":{"type":"object","description":"Response data"},"message":{"type":"string","description":"Response message"},"meta":{"$ref":"#/components/schemas/PaginationMetaDto"}},"required":["success","data"]},"CreateProductDto":{"type":"object","properties":{"name":{"type":"string","description":"Product name","example":"Gaming Laptop","minLength":1,"maxLength":255},"description":{"type":"string","description":"Product description","example":"High-performance gaming laptop with RTX 4060","maxLength":1000},"price":{"type":"number","description":"Product price in USD","example":999.99,"minimum":0},"imageUrl":{"type":"string","description":"Product image URL","example":"https://example.com/images/laptop.jpg"},"categoryId":{"type":"string","description":"Category ID","example":"123e4567-e89b-12d3-a456-426614174000"},"stockQuantity":{"type":"number","description":"Stock quantity","example":50,"minimum":0,"default":0},"isAvailable":{"type":"boolean","description":"Product availability status","example":true,"default":true}},"required":["name","price","categoryId"]},"UpdateProductDto":{"type":"object","properties":{"name":{"type":"string","description":"Product name","example":"Gaming Laptop","minLength":1,"maxLength":255},"description":{"type":"string","description":"Product description","example":"High-performance gaming laptop with RTX 4060","maxLength":1000},"price":{"type":"number","description":"Product price in USD","example":999.99,"minimum":0},"imageUrl":{"type":"string","description":"Product image URL","example":"https://example.com/images/laptop.jpg"},"categoryId":{"type":"string","description":"Category ID","example":"123e4567-e89b-12d3-a456-426614174000"},"stockQuantity":{"type":"number","description":"Stock quantity","example":50,"minimum":0,"default":0},"isAvailable":{"type":"boolean","description":"Product availability status","example":true,"default":true}}},"CreateCategoryDto":{"type":"object","properties":{"name":{"type":"string","description":"Category name","example":"Electronics","minLength":1,"maxLength":255},"description":{"type":"string","description":"Category description","example":"Electronic devices and accessories","maxLength":500},"iconPath":{"type":"string","description":"Icon path or name","example":"/icons/electronics.png"},"color":{"type":"string","description":"Category color in hex format","example":"#FF5722"}},"required":["name"]},"CategoryResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Category ID"},"name":{"type":"string","description":"Category name","example":"Electronics"},"description":{"type":"string","description":"Category description","example":"Electronic devices and accessories"},"iconPath":{"type":"string","description":"Icon path or name","example":"/icons/electronics.png"},"color":{"type":"string","description":"Category color in hex format","example":"#FF5722"},"productCount":{"type":"number","description":"Number of products in this category","example":150},"createdAt":{"format":"date-time","type":"string","description":"Category creation date"},"updatedAt":{"format":"date-time","type":"string","description":"Category last update date"}},"required":["id","name","productCount","createdAt","updatedAt"]},"UpdateCategoryDto":{"type":"object","properties":{"name":{"type":"string","description":"Category name","example":"Electronics","minLength":1,"maxLength":255},"description":{"type":"string","description":"Category description","example":"Electronic devices and accessories","maxLength":500},"iconPath":{"type":"string","description":"Icon path or name","example":"/icons/electronics.png"},"color":{"type":"string","description":"Category color in hex format","example":"#FF5722"}}}}}} |