پرش به مطلب اصلی

دکوراتورهای Swagger

دکوراتورهای Swagger برای مستندسازی APIها در Swagger/OpenAPI استفاده می‌شوند.

swagger.summery​

برای تنظیم خلاصه مسیر API استفاده می‌شود.

@swagger.summery('دریافت لیست کاربران')
@api.get('/users')
async getUsers() {
  // کد پیاده‌سازی
}

swagger.parameters​

برای تعریف پارامترهای API استفاده می‌شود.

@swagger.parameters([
  { name: 'page', type: 'number', default: 1 },
  { name: 'limit', type: 'number', default: 10 }
])
@api.get('/users')
async getUsers() {
  // کد پیاده‌سازی
}

swagger.parametersWithPagination​

برای اضافه کردن پارامترهای صفحه‌بندی به طور خودکار استفاده می‌شود.

@swagger.parametersWithPagination([
  { name: 'search', type: 'string' }
])
@api.get('/users')
async getUsers() {
  // کد پیاده‌سازی
}

این دکوراتور به طور خودکار پارامترهای page و page_size را اضافه می‌کند.

swagger.formDataParameterWithTSInterface​

برای تعریف پارامترهای FormData بر اساس interface TypeScript استفاده می‌شود.

@swagger.formDataParameterWithTSInterface('UserCreateInterface')
@api.post('/users')
async createUser() {
  // کد پیاده‌سازی
}

swagger.queryParameterWithTSInterface​

برای تعریف پارامترهای Query بر اساس interface TypeScript استفاده می‌شود.

@swagger.queryParameterWithTSInterface('UserFilterInterface')
@api.get('/users')
async getUsers() {
  // کد پیاده‌سازی
}

swagger.bodyParameterWithTSInterface​

برای تعریف پارامتر بدنه درخواست بر اساس interface TypeScript استفاده می‌شود.

@swagger.bodyParameterWithTSInterface('UserCreateInterface')
@api.post('/users')
async createUser() {
  // کد پیاده‌سازی
}

swagger.bodyArrayParameterWithTSInterface​

برای تعریف پارامتر بدنه درخواست به صورت آرایه بر اساس interface TypeScript استفاده می‌شود.

@swagger.bodyArrayParameterWithTSInterface('UserInterface')
@api.post('/users/bulk')
async createUsersBulk() {
  // کد پیاده‌سازی
}

swagger.response​

برای تعریف پاسخ‌های API استفاده می‌شود.

@swagger.response(200, {
  description: 'موفقیت',
  schema: { type: 'object', tsDefinition: 'UserInterface' }
})
@api.get('/users/:id')
async getUser() {
  // کد پیاده‌سازی
}

swagger.OkResponseTSInterface​

برای تعریف پاسخ 200 بر اساس interface TypeScript استفاده می‌شود.

@swagger.OkResponseTSInterface('UserInterface')
@api.get('/users/:id')
async getUser() {
  // کد پیاده‌سازی
}

swagger.OkArrayResponseTSInterface​

برای تعریف پاسخ 200 به صورت آرایه بر اساس interface TypeScript استفاده می‌شود.

@swagger.OkArrayResponseTSInterface('UserInterface')
@api.get('/users')
async getUsers() {
  // کد پیاده‌سازی
}

swagger.OkResponseSingleType​

برای تعریف پاسخ 200 با نوع داده ساده استفاده می‌شود.

@swagger.OkResponseSingleType('string')
@api.get('/users/count')
async getUsersCount() {
  // کد پیاده‌سازی
}

swagger.description​

برای تنظیم توضیحات مسیر API استفاده می‌شود. از Markdown پشتیبانی می‌کند.

@swagger.description(`
دریافت اطلاعات کاربر

**نکته**: این API نیاز به احراز هویت دارد.
`)
@api.get('/users/:id')
async getUser() {
  // کد پیاده‌سازی
}

swagger.consumes​

برای تعیین فرمت‌های ورودی API استفاده می‌شود.

@swagger.consumes(['application/json', 'multipart/form-data'])
@api.post('/users')
async createUser() {
  // کد پیاده‌سازی
}

swagger.consumeFormData​

برای تعیین اینکه API از FormData استفاده می‌کند.

@swagger.consumeFormData()
@api.post('/upload')
async uploadFile() {
  // کد پیاده‌سازی
}