docs: enhance Swagger documentation

Author: TeaCoder52

src/api/auth/account/account.controller.ts

@@ -8,12 +8,7 @@ import {
 	Patch,
 	Post
 } from '@nestjs/common'
-import {
-	ApiHeader,
-	ApiOkResponse,
-	ApiOperation,
-	ApiTags
-} from '@nestjs/swagger'
+import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger'
 import type { User } from '@prisma/generated'
 import { Turnstile } from 'nestjs-cloudflare-captcha'
 
@@ -47,10 +42,6 @@ export class AccountController {
 	@ApiOkResponse({
 		type: AccountResponse
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Get()
 	@HttpCode(HttpStatus.OK)
@@ -83,10 +74,6 @@ export class AccountController {
 	@ApiOkResponse({
 		type: Boolean
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Post('verify')
 	@HttpCode(HttpStatus.OK)
@@ -141,10 +128,6 @@ export class AccountController {
 	@ApiOkResponse({
 		type: Boolean
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Patch('change/email')
 	@HttpCode(HttpStatus.OK)
@@ -162,10 +145,6 @@ export class AccountController {
 	@ApiOkResponse({
 		type: Boolean
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Patch('change/password')
 	@HttpCode(HttpStatus.OK)

src/api/auth/mfa/mfa.controller.ts

@@ -11,7 +11,6 @@ import {
 } from '@nestjs/common'
 import {
 	ApiBody,
-	ApiHeader,
 	ApiOkResponse,
 	ApiOperation,
 	ApiTags,
@@ -50,10 +49,6 @@ export class MfaController {
 	@ApiOkResponse({
 		type: MfaStatusResponse
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Get()
 	@HttpCode(HttpStatus.OK)
@@ -68,10 +63,6 @@ export class MfaController {
 	@ApiOkResponse({
 		type: [String]
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Get('recovery')
 	@HttpCode(HttpStatus.OK)
@@ -86,10 +77,6 @@ export class MfaController {
 	@ApiOkResponse({
 		type: [String]
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Patch('recovery')
 	@HttpCode(HttpStatus.OK)
@@ -104,10 +91,6 @@ export class MfaController {
 	@ApiOkResponse({
 		type: Boolean
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Put('totp')
 	@HttpCode(HttpStatus.OK)
@@ -125,10 +108,6 @@ export class MfaController {
 	@ApiOkResponse({
 		type: TotpGenerateSecretResponse
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Post('totp')
 	@HttpCode(HttpStatus.OK)
@@ -143,10 +122,6 @@ export class MfaController {
 	@ApiOkResponse({
 		type: Boolean
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Delete('totp')
 	@HttpCode(HttpStatus.OK)

src/api/auth/passkey/passkey.controller.ts

@@ -8,7 +8,7 @@ import {
 	Param,
 	Post
 } from '@nestjs/common'
-import { ApiHeader, ApiOkResponse, ApiOperation } from '@nestjs/swagger'
+import { ApiOkResponse, ApiOperation } from '@nestjs/swagger'
 import { User } from '@prisma/generated'
 
 import {
@@ -36,7 +36,6 @@ export class PasskeyController {
 			'Retrieve the list of registered passkeys for the authenticated user.'
 	})
 	@ApiOkResponse({ type: [PasskeyResponse] })
-	@ApiHeader({ name: 'X-Session-Token', required: true })
 	@Authorization()
 	@Get()
 	@HttpCode(HttpStatus.OK)
@@ -49,7 +48,6 @@ export class PasskeyController {
 		description: 'Register a passkey for an account.'
 	})
 	@ApiOkResponse({ type: RegisterPasskeyResponse })
-	@ApiHeader({ name: 'X-Session-Token', required: true })
 	@Authorization()
 	@Post()
 	@HttpCode(HttpStatus.OK)
@@ -80,7 +78,6 @@ export class PasskeyController {
 			'Generate options required to initiate WebAuthn registration.'
 	})
 	@ApiOkResponse({ type: GeneratePasskeyOptionsResponse })
-	@ApiHeader({ name: 'X-Session-Token', required: true })
 	@Authorization()
 	@Post('register-options')
 	@HttpCode(HttpStatus.OK)
@@ -93,7 +90,6 @@ export class PasskeyController {
 		description: 'Delete a registered passkey by its ID.'
 	})
 	@ApiOkResponse({ type: Boolean })
-	@ApiHeader({ name: 'X-Session-Token', required: true })
 	@Authorization()
 	@Delete(':id')
 	@HttpCode(HttpStatus.OK)

src/api/auth/sso/sso.controller.ts

@@ -12,12 +12,7 @@ import {
 	UseGuards
 } from '@nestjs/common'
 import { ConfigService } from '@nestjs/config'
-import {
-	ApiHeader,
-	ApiOkResponse,
-	ApiOperation,
-	ApiTags
-} from '@nestjs/swagger'
+import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger'
 import type { User } from '@prisma/generated'
 import { Response } from 'express'
 

src/api/course/course.controller.ts

@@ -10,7 +10,6 @@ import {
 	Res
 } from '@nestjs/common'
 import {
-	ApiHeader,
 	ApiOkResponse,
 	ApiOperation,
 	ApiResponse,
@@ -34,7 +33,8 @@ import {
 	CourseResponse,
 	CoursesResponse,
 	CreateCourseRequest,
-	CreateCourseResponse
+	CreateCourseResponse,
+	GenerateDownloadLinkResponse
 } from './dto'
 
 @ApiTags('Course')
@@ -108,8 +108,12 @@ export class CourseController {
 		await this.courseService.incrementViews(id)
 	}
 
-	@ApiHeader({
-		name: 'X-Session-Token'
+	@ApiOperation({
+		summary: 'Generate download link',
+		description: 'Generates a secure download link for a course.'
+	})
+	@ApiOkResponse({
+		type: GenerateDownloadLinkResponse
 	})
 	@PremiumOnly()
 	@Post(':id/download-link')
@@ -121,8 +125,14 @@ export class CourseController {
 		return await this.courseService.generateDownloadLink(id, user)
 	}
 
-	@ApiHeader({
-		name: 'X-Session-Token'
+	@ApiOperation({
+		summary: 'Resolve download token',
+		description:
+			'Resolves a download token to stream the course attachment.'
+	})
+	@ApiOkResponse({
+		description:
+			'The requested course file is streamed as a ZIP attachment.'
 	})
 	@Get('download/:token')
 	@HttpCode(HttpStatus.OK)
@@ -165,10 +175,6 @@ export class CourseController {
 		status: HttpStatus.OK,
 		type: CreateCourseResponse
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization(UserRole.ADMIN)
 	@Post()
 	@HttpCode(HttpStatus.OK)

src/api/course/dto/generate-download-link.dto.ts

@@ -0,0 +1,9 @@
+import { ApiProperty } from '@nestjs/swagger'
+
+export class GenerateDownloadLinkResponse {
+	@ApiProperty({
+		description: 'URL to download the course',
+		example: 'https://example.com/download/abc123'
+	})
+	public url: string
+}

src/api/course/dto/index.ts

@@ -1,3 +1,4 @@
 export * from './course.dto'
 export * from './courses.dto'
 export * from './create-course.dto'
+export * from './generate-download-link.dto'

src/api/lesson/lesson.controller.ts

@@ -12,12 +12,7 @@ import {
 	UseInterceptors
 } from '@nestjs/common'
 import { FileInterceptor } from '@nestjs/platform-express'
-import {
-	ApiHeader,
-	ApiOkResponse,
-	ApiOperation,
-	ApiTags
-} from '@nestjs/swagger'
+import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger'
 import { type User, UserRole } from '@prisma/generated'
 
 import { Authorization, Authorized } from '@/common/decorators'
@@ -57,10 +52,6 @@ export class LessonController {
 	@ApiOkResponse({
 		type: ProgressResponse
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization()
 	@Get(':id/progress')
 	@HttpCode(HttpStatus.OK)
@@ -78,10 +69,6 @@ export class LessonController {
 	@ApiOkResponse({
 		type: CreateLessonResponse
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization(UserRole.ADMIN)
 	@Post()
 	@HttpCode(HttpStatus.OK)
@@ -93,10 +80,6 @@ export class LessonController {
 		summary: 'Upload Lesson Video',
 		description: 'Upload a video file associated with the lesson.'
 	})
-	@ApiHeader({
-		name: 'X-Session-Token',
-		required: true
-	})
 	@Authorization(UserRole.ADMIN)
 	@UseInterceptors(
 		FileInterceptor('file', {

src/api/payment/dto/init-payment.dto.ts

@@ -4,8 +4,18 @@ import { IsEnum } from 'class-validator'
 
 export class InitPaymentRequest {
 	@ApiProperty({
-		enum: PaymentMethod
+		description: 'Payment method',
+		enum: PaymentMethod,
+		example: PaymentMethod.BANK_CARD
 	})
 	@IsEnum(PaymentMethod)
 	public method: PaymentMethod
 }
+
+export class InitPaymentResponse {
+	@ApiProperty({
+		description: 'URL to complete the payment',
+		example: 'https://yookassa.ru/redirect/123456'
+	})
+	public url: string
+}

src/api/payment/payment.controller.ts

@@ -1,18 +1,23 @@
 import { Body, Controller, HttpCode, HttpStatus, Post } from '@nestjs/common'
-import { ApiHeader } from '@nestjs/swagger'
+import { ApiOkResponse, ApiOperation } from '@nestjs/swagger'
 import type { User } from '@prisma/generated'
 
 import { Authorization, Authorized } from '@/common/decorators'
 
-import { InitPaymentRequest } from './dto'
+import { InitPaymentRequest, InitPaymentResponse } from './dto'
 import { PaymentService } from './payment.service'
 
 @Controller('payment')
 export class PaymentController {
 	public constructor(private readonly paymentService: PaymentService) {}
 
-	@ApiHeader({
-		name: 'X-Session-Token'
+	@ApiOperation({
+		summary: 'Init Payment',
+		description:
+			'Creates a new payment and returns a URL to complete the payment process.'
+	})
+	@ApiOkResponse({
+		type: InitPaymentResponse
 	})
 	@Authorization()
 	@Post('init')
@@ -23,12 +28,4 @@ export class PaymentController {
 	) {
 		return await this.paymentService.create(dto, user)
 	}
-
-	@Post('webhook')
-	@HttpCode(HttpStatus.OK)
-	public async webhook(@Body() dto: any) {
-		console.log('PAYMENT WEBHOOK: ', dto)
-
-		return dto
-	}
 }