feat: add docs and custom exc

src/presentation/routing/kyc.py

@@ -1,27 +1,81 @@
 from fastapi import APIRouter,Depends
-from fastapi.responses import ORJSONResponse
 from src.application.commands import GetKycSessionCommand,PassKycCommand
-from src.application.domain.dto import AuthContext
+from src.application.domain.dto import AuthContext,BeorgKycCreateResponse,KycSessionResponse
 from src.presentation.decorators.auth import require_access_token
 from src.presentation.dependencies.commands import get_kyc_session_command,get_pass_kyc_command
+from src.presentation.schemas import ErrorResponse
 
 
 kyc_router = APIRouter(prefix='/kyc', tags=['Kyc'])
 
+CREATE_KYC_RESPONSES = {
+    400: {
+        'model': ErrorResponse,
+        'description': 'Beorg rejected request. error.code: beorg_rejected',
+    },
+    401: {
+        'model': ErrorResponse,
+        'description': 'Authentication error. error.code: not_authenticated, invalid_token',
+    },
+    500: {
+        'model': ErrorResponse,
+        'description': 'Configuration or internal error. error.code: beorg_not_configured, internal_server_error',
+    },
+    502: {
+        'model': ErrorResponse,
+        'description': 'Beorg is unavailable. error.code: beorg_unavailable',
+    },
+    422: {
+        'model': ErrorResponse,
+        'description': 'Request validation error. error.code: request_validation_error',
+    },
+}
 
-@kyc_router.post('/create')
+GET_KYC_SESSION_RESPONSES = {
+    401: {
+        'model': ErrorResponse,
+        'description': 'Authentication error. error.code: not_authenticated, invalid_token',
+    },
+    404: {
+        'model': ErrorResponse,
+        'description': 'Active KYC session was not found. error.code: kyc_session_expired',
+    },
+    500: {
+        'model': ErrorResponse,
+        'description': 'Internal error. error.code: internal_server_error',
+    },
+    422: {
+        'model': ErrorResponse,
+        'description': 'Request validation error. error.code: request_validation_error',
+    },
+}
+
+
+@kyc_router.post(
+    '/create',
+    response_model=BeorgKycCreateResponse,
+    responses=CREATE_KYC_RESPONSES,
+    summary='Start KYC session',
+    description='Creates a Beorg KYC session for one hour and returns link, user token and QR code.',
+)
 async def create_kyc(
         #auth: AuthContext = Depends(require_access_token),
         command: PassKycCommand = Depends(get_pass_kyc_command),
-) -> ORJSONResponse:
+) -> BeorgKycCreateResponse:
     result = await command(user_id='01KPKAFN6J1NJBY15DX8JE2QYB')
-    return ORJSONResponse(result.model_dump())
+    return result
 
 
-@kyc_router.get('/session')
+@kyc_router.get(
+    '/session',
+    response_model=KycSessionResponse,
+    responses=GET_KYC_SESSION_RESPONSES,
+    summary='Get KYC session',
+    description='Returns latest KYC session status, link, QR code and expiration data.',
+)
 async def get_kyc_session(
         #auth: AuthContext = Depends(require_access_token),
         command: GetKycSessionCommand = Depends(get_kyc_session_command),
-) -> ORJSONResponse:
+) -> KycSessionResponse:
     result = await command(user_id='01KPKAFN6J1NJBY15DX8JE2QYB')
-    return ORJSONResponse(result.model_dump())
+    return result