Skip to content

Commit 0786ad2

Browse files
author
Lasim
committed
feat(backend): enhance login API response with detailed descriptions
1 parent 2d9b3f4 commit 0786ad2

File tree

3 files changed

+354
-345
lines changed

3 files changed

+354
-345
lines changed

‎services/backend/api-spec.json‎

Lines changed: 106 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -18820,11 +18820,13 @@
1882018820
"properties": {
1882118821
"login": {
1882218822
"type": "string",
18823-
"minLength": 1
18823+
"minLength": 1,
18824+
"description": "User's registered email address or username"
1882418825
},
1882518826
"password": {
1882618827
"type": "string",
18827-
"minLength": 1
18828+
"minLength": 1,
18829+
"description": "User's password"
1882818830
}
1882918831
},
1883018832
"required": [
@@ -18837,193 +18839,145 @@
1883718839
},
1883818840
"required": true
1883918841
},
18840-
"security": [
18841-
{
18842-
"cookieAuth": []
18843-
}
18844-
],
1884518842
"responses": {
1884618843
"200": {
18847-
"description": "Default Response",
18844+
"description": "Login successful. Session cookie is set.",
1884818845
"content": {
1884918846
"application/json": {
1885018847
"schema": {
18851-
"schema": {
18852-
"description": "Login successful. Session cookie is set.",
18853-
"type": "object",
18854-
"properties": {
18855-
"success": {
18856-
"description": "Indicates if the login operation was successful.",
18857-
"type": "boolean"
18858-
},
18859-
"message": {
18860-
"description": "Human-readable message about the login result.",
18861-
"type": "string"
18862-
},
18863-
"user": {
18864-
"description": "Basic information about the logged-in user.",
18865-
"type": "object",
18866-
"properties": {
18867-
"id": {
18868-
"description": "User ID",
18869-
"type": "string"
18870-
},
18871-
"email": {
18872-
"description": "User's primary email address.",
18873-
"type": "string",
18874-
"format": "email",
18875-
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
18876-
},
18877-
"username": {
18878-
"description": "User's username.",
18879-
"anyOf": [
18880-
{
18881-
"type": "string"
18882-
},
18883-
{
18884-
"type": "null"
18885-
}
18886-
]
18887-
},
18888-
"first_name": {
18889-
"description": "User's first name.",
18890-
"anyOf": [
18891-
{
18892-
"type": "string"
18893-
},
18894-
{
18895-
"type": "null"
18896-
}
18897-
]
18898-
},
18899-
"last_name": {
18900-
"description": "User's last name.",
18901-
"anyOf": [
18902-
{
18903-
"type": "string"
18904-
},
18905-
{
18906-
"type": "null"
18907-
}
18908-
]
18909-
},
18910-
"role_id": {
18911-
"description": "User's role ID.",
18912-
"anyOf": [
18913-
{
18914-
"type": "string"
18915-
},
18916-
{
18917-
"type": "null"
18918-
}
18919-
]
18920-
}
18921-
},
18922-
"required": [
18923-
"id",
18924-
"email"
18925-
],
18926-
"additionalProperties": false
18927-
}
18848+
"type": "object",
18849+
"properties": {
18850+
"success": {
18851+
"type": "boolean",
18852+
"description": "Indicates if the login operation was successful"
1892818853
},
18929-
"required": [
18930-
"success",
18931-
"message",
18932-
"user"
18933-
],
18934-
"additionalProperties": false
18854+
"message": {
18855+
"type": "string",
18856+
"description": "Human-readable message about the login result"
18857+
},
18858+
"user": {
18859+
"type": "object",
18860+
"properties": {
18861+
"id": {
18862+
"type": "string",
18863+
"description": "User ID"
18864+
},
18865+
"email": {
18866+
"type": "string",
18867+
"format": "email",
18868+
"description": "User's primary email address"
18869+
},
18870+
"username": {
18871+
"type": "string",
18872+
"nullable": true,
18873+
"description": "User's username"
18874+
},
18875+
"first_name": {
18876+
"type": "string",
18877+
"nullable": true,
18878+
"description": "User's first name"
18879+
},
18880+
"last_name": {
18881+
"type": "string",
18882+
"nullable": true,
18883+
"description": "User's last name"
18884+
},
18885+
"role_id": {
18886+
"type": "string",
18887+
"nullable": true,
18888+
"description": "User's role ID"
18889+
}
18890+
},
18891+
"required": [
18892+
"id",
18893+
"email"
18894+
]
18895+
}
1893518896
},
18936-
"components": {}
18897+
"required": [
18898+
"success",
18899+
"message",
18900+
"user"
18901+
],
18902+
"description": "Login successful. Session cookie is set."
1893718903
}
1893818904
}
1893918905
}
1894018906
},
1894118907
"400": {
18942-
"description": "Default Response",
18908+
"description": "Bad Request - Invalid input, invalid credentials, or missing Content-Type header",
1894318909
"content": {
1894418910
"application/json": {
1894518911
"schema": {
18946-
"schema": {
18947-
"description": "Bad Request - Invalid input, invalid credentials, or missing Content-Type header.",
18948-
"type": "object",
18949-
"properties": {
18950-
"success": {
18951-
"default": false,
18952-
"description": "Indicates if the operation was successful (typically false for errors).",
18953-
"type": "boolean"
18954-
},
18955-
"error": {
18956-
"description": "Error message.",
18957-
"type": "string"
18958-
}
18912+
"type": "object",
18913+
"properties": {
18914+
"success": {
18915+
"type": "boolean",
18916+
"default": false,
18917+
"description": "Indicates the operation failed"
1895918918
},
18960-
"required": [
18961-
"success",
18962-
"error"
18963-
],
18964-
"additionalProperties": false
18919+
"error": {
18920+
"type": "string",
18921+
"description": "Error message describing what went wrong"
18922+
}
1896518923
},
18966-
"components": {}
18924+
"required": [
18925+
"success",
18926+
"error"
18927+
],
18928+
"description": "Bad Request - Invalid input, invalid credentials, or missing Content-Type header"
1896718929
}
1896818930
}
1896918931
}
1897018932
},
1897118933
"403": {
18972-
"description": "Default Response",
18934+
"description": "Forbidden - Login is disabled by administrator",
1897318935
"content": {
1897418936
"application/json": {
1897518937
"schema": {
18976-
"schema": {
18977-
"description": "Forbidden - Login is disabled by administrator.",
18978-
"type": "object",
18979-
"properties": {
18980-
"success": {
18981-
"default": false,
18982-
"description": "Indicates if the operation was successful (typically false for errors).",
18983-
"type": "boolean"
18984-
},
18985-
"error": {
18986-
"description": "Error message.",
18987-
"type": "string"
18988-
}
18938+
"type": "object",
18939+
"properties": {
18940+
"success": {
18941+
"type": "boolean",
18942+
"default": false,
18943+
"description": "Indicates the operation failed"
1898918944
},
18990-
"required": [
18991-
"success",
18992-
"error"
18993-
],
18994-
"additionalProperties": false
18945+
"error": {
18946+
"type": "string",
18947+
"description": "Error message describing what went wrong"
18948+
}
1899518949
},
18996-
"components": {}
18950+
"required": [
18951+
"success",
18952+
"error"
18953+
],
18954+
"description": "Forbidden - Login is disabled by administrator"
1899718955
}
1899818956
}
1899918957
}
1900018958
},
1900118959
"500": {
19002-
"description": "Default Response",
18960+
"description": "Internal Server Error - An unexpected error occurred on the server",
1900318961
"content": {
1900418962
"application/json": {
1900518963
"schema": {
19006-
"schema": {
19007-
"description": "Internal Server Error - An unexpected error occurred on the server.",
19008-
"type": "object",
19009-
"properties": {
19010-
"success": {
19011-
"default": false,
19012-
"description": "Indicates if the operation was successful (typically false for errors).",
19013-
"type": "boolean"
19014-
},
19015-
"error": {
19016-
"description": "Error message.",
19017-
"type": "string"
19018-
}
18964+
"type": "object",
18965+
"properties": {
18966+
"success": {
18967+
"type": "boolean",
18968+
"default": false,
18969+
"description": "Indicates the operation failed"
1901918970
},
19020-
"required": [
19021-
"success",
19022-
"error"
19023-
],
19024-
"additionalProperties": false
18971+
"error": {
18972+
"type": "string",
18973+
"description": "Error message describing what went wrong"
18974+
}
1902518975
},
19026-
"components": {}
18976+
"required": [
18977+
"success",
18978+
"error"
18979+
],
18980+
"description": "Internal Server Error - An unexpected error occurred on the server"
1902718981
}
1902818982
}
1902918983
}

0 commit comments

Comments
 (0)