Welcome!

Swagger یک ابزار برای توصیف و مستندسازی API ها است. برای این کار شما باید از مکانیزم احراز هویت و اجازهدهی استفاده کنید. یکی از روشهای متداول برای این کار استفاده از توکن JWT است. JWT یک رشتهی رمزگذاری شده است که حاوی اطلاعات کاربر است. شما میتوانید این توکن را در هدر Authorization ارسال کنید و در سمت سرور آن را بازگشایی و اعتبارسنجی کنید. برای این کار شما باید در فایل تعریف Swagger خود مشخص کنید که API شما از چه نوع احراز هویتی استفاده میکند. مثلا:

securityDefinitions:
jwt:
type: apiKey
name: Authorization
in: header
security:
•  jwt: []


این کد نشان میدهد که API شما از یک کلید API در هدر درخواست با نام Authorization استفاده میکند. همچنین در هر مسیری که نیاز به احراز هویت دارد، باید این کد را قرار دهید:

security:
•  jwt: []


این کد نشان میدهد که این مسیر از مکانیزم احراز هویت jwt استفاده میکند. برای مثال، اگر شما یک مسیر برای بهروزرسانی اطلاعات کاربر داشته باشید، میتوانید این کد را بنویسید:

paths:
/users/{id}:
put:
summary: Update user information
parameters:
•  in: path

name: id
required: true
type: integer
description: The user id
•  in: body

name: user
required: true
schema:
$ref: '#/definitions/User'
responses:
200:
description: User updated successfully
schema:
$ref: '#/definitions/User'
401:
description: Unauthorized
404:
description: User not found
security:
•  jwt: []


این کد نشان میدهد که شما میتوانید با ارسال یک درخواست put به مسیر /users/{id} اطلاعات کاربر را بهروزرسانی کنید. اما برای این کار باید یک توکن jwt معتبر در هدر Authorization داشته باشید. در غیر این صورت، شما یک پاسخ 401 Unauthorized دریافت خواهید کرد. همچنین اگر کاربری با شناسهی مورد نظر وجود نداشته باشد، شما یک پاسخ 404 User not found دریافت خواهید کرد.