From 24137beb328e231e6129057d9eb30ff6d121c8e3 Mon Sep 17 00:00:00 2001
From: parsaaghayi <parsa.aghaee@gmail.com>
Date: Fri, 12 Jun 2026 23:30:22 +0330
Subject: [PATCH] docs: complete swagger annotations for auth, home, blogs and
 wiki endpoints

---
 backend/src/auth/auth.controller.ts   |  6 ++++++
 backend/src/blogs/blogs.controller.ts | 13 ++++++++++++-
 backend/src/home/home.controller.ts   | 10 +++++++++-
 backend/src/wiki/wiki.controller.ts   | 13 ++++++++++++-
 4 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/backend/src/auth/auth.controller.ts b/backend/src/auth/auth.controller.ts
index fc5323f..8043d8a 100644
--- a/backend/src/auth/auth.controller.ts
+++ b/backend/src/auth/auth.controller.ts
@@ -97,6 +97,8 @@ export class AuthController {
   @Post('register')
   @HttpCode(HttpStatus.CREATED)
   @ApiOperation({ summary: 'ثبت‌نام با ایمیل/موبایل و رمز عبور' })
+  @ApiOkResponse({ description: 'کاربر با موفقیت ثبت‌نام شد' })
+  @ApiBadRequestResponse({ description: 'اطلاعات ثبت‌نام نامعتبر است یا کاربر از قبل وجود دارد' })
   register(@Body() registerDto: RegisterDto) {
     return this.authService.register(registerDto);
   }
@@ -104,6 +106,8 @@ export class AuthController {
   @Post('login')
   @HttpCode(HttpStatus.OK)
   @ApiOperation({ summary: 'ورود با موبایل و رمز عبور' })
+  @ApiOkResponse({ description: 'ورود موفق به همراه توکن دسترسی' })
+  @ApiBadRequestResponse({ description: 'نام کاربری یا رمز عبور اشتباه است' })
   login(@Body() loginDto: LoginDto) {
     return this.authService.login(loginDto);
   }
@@ -111,6 +115,8 @@ export class AuthController {
   @Post('admin-login')
   @HttpCode(HttpStatus.OK)
   @ApiOperation({ summary: 'ورود ادمین به پنل مدیریت' })
+  @ApiOkResponse({ description: 'ورود موفق ادمین به همراه توکن' })
+  @ApiBadRequestResponse({ description: 'اطلاعات ورود ادمین اشتباه است' })
   adminLogin(@Body() body: any) {
     return this.authService.adminLogin(body);
   }
diff --git a/backend/src/blogs/blogs.controller.ts b/backend/src/blogs/blogs.controller.ts
index 6b6c0be..6f29550 100644
--- a/backend/src/blogs/blogs.controller.ts
+++ b/backend/src/blogs/blogs.controller.ts
@@ -1,16 +1,27 @@
-import { Controller, Get, Param } from '@nestjs/common';
+import { Controller, Get, Param, HttpStatus } from '@nestjs/common';
 import { BlogsService } from './blogs.service';
+import { ApiTags, ApiOperation, ApiResponse, ApiOkResponse, ApiNotFoundResponse } from '@nestjs/swagger';
 
+@ApiTags('Blogs - مجله سلامت')
 @Controller('blogs')
+@ApiResponse({
+  status: HttpStatus.INTERNAL_SERVER_ERROR,
+  description: 'خطای داخلی سرور'
+})
 export class BlogsController {
   constructor(private readonly blogsService: BlogsService) {}
 
   @Get()
+  @ApiOperation({ summary: 'دریافت لیست مقالات مجله سلامت' })
+  @ApiOkResponse({ description: 'لیست مقالات منتشر شده' })
   findAll() {
     return this.blogsService.findAll();
   }
 
   @Get(':slug')
+  @ApiOperation({ summary: 'دریافت مقاله با اسلاگ (Slug)' })
+  @ApiOkResponse({ description: 'اطلاعات کامل مقاله' })
+  @ApiNotFoundResponse({ description: 'مقاله یافت نشد' })
   findOne(@Param('slug') slug: string) {
     return this.blogsService.findOneBySlug(slug);
   }
diff --git a/backend/src/home/home.controller.ts b/backend/src/home/home.controller.ts
index fee5f5c..f3e5ec3 100644
--- a/backend/src/home/home.controller.ts
+++ b/backend/src/home/home.controller.ts
@@ -1,11 +1,19 @@
-import { Controller, Get } from '@nestjs/common';
+import { Controller, Get, HttpStatus } from '@nestjs/common';
 import { HomeService } from './home.service';
+import { ApiTags, ApiOperation, ApiResponse, ApiOkResponse } from '@nestjs/swagger';
 
+@ApiTags('Home - صفحه اصلی')
 @Controller('home')
+@ApiResponse({
+  status: HttpStatus.INTERNAL_SERVER_ERROR,
+  description: 'خطای داخلی سرور'
+})
 export class HomeController {
   constructor(private readonly homeService: HomeService) {}
 
   @Get()
+  @ApiOperation({ summary: 'دریافت اطلاعات صفحه اصلی' })
+  @ApiOkResponse({ description: 'اطلاعات ویترین، بنرها، پرفروش‌ترین‌ها، وبلاگ و غیره' })
   getHomeData() {
     return this.homeService.getHomeData();
   }
diff --git a/backend/src/wiki/wiki.controller.ts b/backend/src/wiki/wiki.controller.ts
index 2614cc9..863ac32 100644
--- a/backend/src/wiki/wiki.controller.ts
+++ b/backend/src/wiki/wiki.controller.ts
@@ -1,16 +1,27 @@
-import { Controller, Get, Param } from '@nestjs/common';
+import { Controller, Get, Param, HttpStatus } from '@nestjs/common';
 import { WikiService } from './wiki.service';
+import { ApiTags, ApiOperation, ApiResponse, ApiOkResponse, ApiNotFoundResponse } from '@nestjs/swagger';
 
+@ApiTags('Wiki - دانشنامه ترکیبات')
 @Controller('wiki')
+@ApiResponse({
+  status: HttpStatus.INTERNAL_SERVER_ERROR,
+  description: 'خطای داخلی سرور'
+})
 export class WikiController {
   constructor(private readonly wikiService: WikiService) {}
 
   @Get()
+  @ApiOperation({ summary: 'دریافت تمام کلمات دانشنامه' })
+  @ApiOkResponse({ description: 'لیست تمامی ترکیبات علمی' })
   findAll() {
     return this.wikiService.findAll();
   }
 
   @Get(':key')
+  @ApiOperation({ summary: 'دریافت ترکیب علمی با کلید' })
+  @ApiOkResponse({ description: 'اطلاعات کامل ترکیب علمی' })
+  @ApiNotFoundResponse({ description: 'ترکیب علمی یافت نشد' })
   findOne(@Param('key') key: string) {
     return this.wikiService.findOneByKey(key);
   }