گزینه‌های اصلی پیکربندی Postman SDK

گزینه‌های اصلی در فایل پیکربندی SDK

گزینه‌های اصلی Postman SDK، تنظیمات پایه تولید SDK را مشخص می‌کنند؛ مثل نام SDK، نام و نسخه API، آدرس پایه API، زبان‌هایی که باید برای آن‌ها SDK ساخته شود و روش احراز هویت. این گزینه‌ها در سطح اصلی فایل postman-sdk.config.json قرار می‌گیرند.

sdkName

با sdkName نام SDK را تعیین می‌کنید. Postman از این نام برای نام بسته، نام کلاس اصلی SDK، README و مستندات تولیدشده استفاده می‌کند.

نام واردشده برای هر زبان به شکل رایج همان زبان تبدیل می‌شود. برای مثال یک نام ممکن است در Java به شکل PascalCase و در packageها به شکل مناسب همان محیط استفاده شود.

apiName

apiName نام API شماست و در مستندات و README SDK نمایش داده می‌شود. اگر این مقدار را در فایل پیکربندی ننویسید، Postman آن را از مشخصات API می‌خواند.

در Swagger و OpenAPI، این مقدار معمولا از info.title خوانده می‌شود:

{
  "openapi": "3.1.0",
  "info": {
    "title": "ExcitingSoda"
  }
}

در Postman Collection، این مقدار از info.name خوانده می‌شود:

{
  "info": {
    "name": "ExcitingSoda"
  }
}

نام API برای Swagger، OpenAPI و Collection ضروری است. اگر نه در فایل پیکربندی باشد و نه در specification، تولید SDK با خطا متوقف می‌شود.

apiVersion

apiVersion نسخه API را مشخص می‌کند. اگر آن را در فایل پیکربندی ننویسید، Postman تلاش می‌کند نسخه را از مشخصات API بخواند.

در OpenAPI این مقدار معمولا در info.version قرار دارد:

{
  "openapi": "3.1.0",
  "info": {
    "title": "ExcitingSoda",
    "version": "1.0.1"
  }
}

در Collection هم می‌تواند در info.version قرار بگیرد:

{
  "info": {
    "name": "ExcitingSoda",
    "version": "1.0.1"
  }
}

حتی اگر این فیلد در خود فایل پیکربندی اختیاری به نظر برسد، برای تولید SDK به یک مقدار نسخه نیاز است. اگر Postman نتواند نسخه را پیدا کند، خطا می‌دهد.

baseUrl

baseUrl آدرس پایه API است؛ همان آدرسی که SDK درخواست‌ها را به آن ارسال می‌کند. اگر این گزینه را تنظیم نکنید، Postman معمولا اولین مقدار موجود در بخش servers مشخصات API را استفاده می‌کند.

در SDKهای Java، اگر گزینه اختصاصی groupId را تنظیم نکرده باشید، مقدار baseUrl برای ساخت groupId هم استفاده می‌شود. مثلا:

{
  "baseUrl": "https://exciting.soda"
}

می‌تواند به groupId زیر تبدیل شود:

<groupId>soda.exciting</groupId>

برای تنظیم URLها در زمان اجرا، به راهنمای استفاده همان زبان SDK مراجعه کنید.

languages

گزینه languages آرایه‌ای از زبان‌هایی است که می‌خواهید برای آن‌ها SDK تولید شود.

{
  "languages": [
    "java",
    "kotlin",
    "python",
    "typescript",
    "csharp",
    "go",
    "php",
    "ruby"
  ]
}

تنظیمات مخصوص هر زبان در بخش languageOptions انجام می‌شود.

auth

گزینه auth روش احراز هویت API را مشخص می‌کند. این گزینه اختیاری است. اگر آن را تنظیم نکنید، SDK تولیدشده بخش احراز هویت اضافه نخواهد داشت.

{
  "auth": ["apikey"]
}

مقادیر معتبر:

مقدار	کاربرد
apikey	ارسال API key در یک header برای همه درخواست‌ها.
basic	ارسال نام کاربری و رمز عبور در header احراز هویت.
bearer	ارسال Bearer token در header احراز هویت.
custom	ارسال access token با پیشوند سفارشی.
oauth	استفاده از OAuth برای دریافت و ارسال access token.

اگر API چند روش احراز هویت دارد، فقط روش‌هایی را همزمان انتخاب کنید که با هم تداخل ندارند. مثلا Basic و Bearer هر دو از header احراز هویت استفاده می‌کنند و معمولا نباید همزمان فعال شوند.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.