Skip to content

Commit 86fba41

Browse files
JasonKrikJasonKrik
committed
feat: implement user login via email/password and update API documentation
1 parent 48e2a51 commit 86fba41

File tree

4 files changed

+465
-109
lines changed

4 files changed

+465
-109
lines changed

‎services/backend/api-spec.json‎

Lines changed: 214 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -61,69 +61,6 @@
6161
}
6262
}
6363
},
64-
"/login": {
65-
"post": {
66-
"responses": {
67-
"200": {
68-
"description": "Default Response"
69-
}
70-
}
71-
}
72-
},
73-
"/logout": {
74-
"post": {
75-
"summary": "User logout",
76-
"tags": [
77-
"Authentication"
78-
],
79-
"description": "Invalidates the current user session and clears authentication cookies. This endpoint can be called even without an active session.",
80-
"security": [
81-
{
82-
"cookieAuth": []
83-
}
84-
],
85-
"responses": {
86-
"200": {
87-
"description": "Default Response",
88-
"content": {
89-
"application/json": {
90-
"schema": {
91-
"type": "object",
92-
"properties": {
93-
"success": {
94-
"type": "boolean",
95-
"description": "Indicates if the logout operation was successful"
96-
},
97-
"message": {
98-
"type": "string",
99-
"description": "Human-readable message about the logout result"
100-
}
101-
},
102-
"required": [
103-
"success",
104-
"message"
105-
]
106-
},
107-
"examples": {
108-
"example1": {
109-
"value": {
110-
"success": true,
111-
"message": "Logged out successfully."
112-
}
113-
},
114-
"example2": {
115-
"value": {
116-
"success": true,
117-
"message": "No active session to logout or already logged out."
118-
}
119-
}
120-
}
121-
}
122-
}
123-
}
124-
}
125-
}
126-
},
12764
"/api/roles": {
12865
"get": {
12966
"responses": {
@@ -473,9 +410,221 @@
473410
},
474411
"/api/auth/email/login": {
475412
"post": {
413+
"summary": "User login via email/password",
414+
"tags": [
415+
"Authentication"
416+
],
417+
"description": "Authenticates a user using their registered identifier (email or username) and password. This endpoint is accessed via the /api/auth/email/login path due to server-level prefixing. Establishes a session by setting an authentication cookie.",
418+
"requestBody": {
419+
"content": {
420+
"application/json": {
421+
"schema": {
422+
"type": "object",
423+
"properties": {
424+
"login": {
425+
"type": "string",
426+
"description": "User's registered email address or username."
427+
},
428+
"password": {
429+
"type": "string",
430+
"description": "User's password."
431+
}
432+
},
433+
"required": [
434+
"login",
435+
"password"
436+
]
437+
}
438+
}
439+
},
440+
"required": true
441+
},
442+
"security": [
443+
{
444+
"cookieAuth": []
445+
}
446+
],
476447
"responses": {
477448
"200": {
478-
"description": "Default Response"
449+
"description": "Login successful. Session cookie is set.",
450+
"content": {
451+
"application/json": {
452+
"schema": {
453+
"description": "Login successful. Session cookie is set.",
454+
"type": "object",
455+
"properties": {
456+
"success": {
457+
"type": "boolean",
458+
"description": "Indicates if the login operation was successful."
459+
},
460+
"message": {
461+
"type": "string",
462+
"description": "Human-readable message about the login result."
463+
},
464+
"user": {
465+
"type": "object",
466+
"description": "Basic information about the logged-in user.",
467+
"properties": {
468+
"id": {
469+
"type": "string",
470+
"description": "User ID"
471+
},
472+
"email": {
473+
"type": "string",
474+
"format": "email",
475+
"description": "User's primary email address."
476+
},
477+
"username": {
478+
"type": "string",
479+
"nullable": true
480+
},
481+
"first_name": {
482+
"type": "string",
483+
"nullable": true
484+
},
485+
"last_name": {
486+
"type": "string",
487+
"nullable": true
488+
},
489+
"role_id": {
490+
"type": "string",
491+
"nullable": true
492+
}
493+
},
494+
"required": [
495+
"id",
496+
"email"
497+
]
498+
}
499+
},
500+
"required": [
501+
"success",
502+
"message",
503+
"user"
504+
]
505+
},
506+
"example": {
507+
"success": true,
508+
"message": "Logged in successfully.",
509+
"user": {
510+
"id": "clxyz1234000008l3abcde123",
511+
"email": "user@example.com",
512+
"username": "testuser",
513+
"first_name": "Test",
514+
"last_name": "User",
515+
"role_id": "user_role_id"
516+
}
517+
}
518+
}
519+
}
520+
},
521+
"400": {
522+
"description": "Bad Request - Invalid input or invalid credentials.",
523+
"content": {
524+
"application/json": {
525+
"schema": {
526+
"description": "Bad Request - Invalid input or invalid credentials.",
527+
"type": "object",
528+
"properties": {
529+
"success": {
530+
"type": "boolean"
531+
},
532+
"error": {
533+
"type": "string",
534+
"description": "Error message."
535+
}
536+
},
537+
"required": [
538+
"success",
539+
"error"
540+
]
541+
},
542+
"examples": {
543+
"example1": {
544+
"value": {
545+
"success": false,
546+
"error": "Email/username and password are required."
547+
}
548+
},
549+
"example2": {
550+
"value": {
551+
"success": false,
552+
"error": "Invalid email/username or password."
553+
}
554+
}
555+
}
556+
}
557+
}
558+
},
559+
"403": {
560+
"description": "Forbidden - Login is disabled by administrator.",
561+
"content": {
562+
"application/json": {
563+
"schema": {
564+
"description": "Forbidden - Login is disabled by administrator.",
565+
"type": "object",
566+
"properties": {
567+
"success": {
568+
"type": "boolean"
569+
},
570+
"error": {
571+
"type": "string"
572+
}
573+
},
574+
"required": [
575+
"success",
576+
"error"
577+
]
578+
},
579+
"example": {
580+
"success": false,
581+
"error": "Login is currently disabled by administrator."
582+
}
583+
}
584+
}
585+
},
586+
"500": {
587+
"description": "Internal Server Error - An unexpected error occurred on the server.",
588+
"content": {
589+
"application/json": {
590+
"schema": {
591+
"description": "Internal Server Error - An unexpected error occurred on the server.",
592+
"type": "object",
593+
"properties": {
594+
"success": {
595+
"type": "boolean"
596+
},
597+
"error": {
598+
"type": "string"
599+
}
600+
},
601+
"required": [
602+
"success",
603+
"error"
604+
]
605+
},
606+
"examples": {
607+
"example1": {
608+
"value": {
609+
"success": false,
610+
"error": "An unexpected error occurred during login."
611+
}
612+
},
613+
"example2": {
614+
"value": {
615+
"success": false,
616+
"error": "Internal server error: User table configuration missing."
617+
}
618+
},
619+
"example3": {
620+
"value": {
621+
"success": false,
622+
"error": "User ID not found."
623+
}
624+
}
625+
}
626+
}
627+
}
479628
}
480629
}
481630
}
@@ -556,7 +705,7 @@
556705
"servers": [
557706
{
558707
"url": "http://localhost:3000",
559-
"description": "Development server"
708+
"description": "Server"
560709
}
561710
]
562711
}

0 commit comments

Comments
 (0)