پیکربندی تولید SDK در Postman

برای کنترل خروجی SDK Generator می‌توانید از فایل پیکربندی Postman SDK استفاده کنید. این فایل مشخص می‌کند SDK با چه نام package، چه زبان، چه گزینه‌هایی برای code generation و چه تنظیمات پیشرفته‌ای ساخته شود.

ساخت و مدیریت فایل config تولید SDK #

فایل config معمولا در کنار collection یا specification و کد SDK نگهداری می‌شود تا تنظیمات generation قابل تکرار و قابل review باشد. اگر SDK را در Git نگه می‌دارید، این فایل را هم commit کنید تا تیم بتواند همان خروجی را دوباره تولید کند.

برای شروع، یک فایل config بسازید و زبان، نام package، مسیر خروجی و گزینه‌های مورد نیاز را در آن قرار دهید. سپس هنگام اجرای generation از همان فایل استفاده کنید.

postman sdk generate <id or path> --config postman-sdk.config.json

ساختار فایل config #

ساختار دقیق فایل به زبان و نسخه generator بستگی دارد، اما معمولا شامل بخش‌هایی برای زبان، package metadata، output، authentication، validation، transport و گزینه‌های merge است.

{
  "language": "typescript",
  "packageName": "@your-org/your-sdk",
  "outputDirectory": "./sdks/typescript",
  "generator": {
    "validation": true,
    "docs": true,
    "examples": true
  },
  "transport": {
    "type": "fetch"
  }
}

گزینه‌های رایج #

• language: زبان خروجی مثل TypeScript، Python، Java، Go، PHP، Ruby یا Rust.
• packageName: نام package یا module در ecosystem همان زبان.
• outputDirectory: مسیر ذخیره فایل‌های تولیدشده.
• validation: فعال یا غیرفعال کردن validation بر اساس specification.
• docs و examples: تولید مستندات و نمونه کد همراه SDK.
• transport: انتخاب client یا transport مناسب، مثل fetch یا axios برای TypeScript.

تنظیمات پیشرفته #

در پروژه‌های واقعی ممکن است لازم باشد naming، namespace، serialization، retry، timeout، environmentها و نحوه merge شدن کد سفارشی را تنظیم کنید. این گزینه‌ها کمک می‌کنند SDK خروجی با استانداردهای داخلی تیم شما هماهنگ شود.

• برای SDKهای enterprise، config را در repository نگه دارید و تغییرات آن را code review کنید.
• برای چند زبان، برای هر زبان config جداگانه بسازید تا package metadata و output path مخلوط نشوند.
• اگر کد سفارشی اضافه می‌کنید، تنظیمات merge و regeneration را با دقت نگه دارید.
• برای CI/CD، مسیر خروجی و command generation را ثابت کنید تا build قابل تکرار باشد.

پیشنهاد عملی #

اول با config ساده شروع کنید: زبان، package name و output directory. بعد از اینکه SDK درست ساخته شد، validation، documentation، examples و گزینه‌های transport یا retry را مرحله‌به‌مرحله اضافه کنید. این روش عیب‌یابی خطاهای generation را ساده‌تر می‌کند.

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