خودکارسازی به‌روزرسانی SDK با Postman و GitHub

به‌روزرسانی خودکار SDK با GitHub

Postman می‌تواند از روی Collection یا specification، SDK بسازد و آن را به یک repository در GitHub وصل کند. بعد از اتصال، تغییرات Collection یا specification می‌توانند باعث ساخت SDK جدید و ایجاد Pull Request در repository شوند.

این قابلیت برای به‌روزرسانی خودکار SDK در پلن‌های Enterprise Postman در دسترس است. در پلن Team می‌توانید SDK را به GitHub وصل کنید و دستی به‌روزرسانی کنید، اما PR خودکار برای تغییرات API به Enterprise نیاز دارد.

PRهای خودکار معمولا در این حالت‌ها ساخته می‌شوند:

• وقتی Collection یا specification تغییر کند؛ مثلا request اضافه، حذف یا ویرایش شود.
• وقتی نسخه جدید SDK Generator منتشر شود و Postman بخواهد SDKها را با bug fixها، قابلیت‌های جدید یا به‌روزرسانی‌های امنیتی بازسازی کند.

Postman کدهای سفارشی شما را هم در بازتولید خودکار حفظ می‌کند. برای این کار، تغییرات repository از آخرین PR merge‌شده بررسی می‌شود و با خروجی جدید SDK ادغام می‌شود.

پیش‌نیازها

• یک Postman Collection با حداقل یک request ذخیره‌شده.
• یک حساب GitHub با دسترسی به organization یا repository مقصد.
• نصب بودن Postman GitHub app روی حساب یا organization مورد نظر.

مرحله ۱: تولید SDK از Collection

لازم نیست همیشه SDK را دوباره تولید کنید؛ کافی است قبلا یک بار SDK ساخته باشید. بعد از اتصال SDK به GitHub، تغییرات آینده Collection می‌توانند به‌روزرسانی SDK را فعال کنند.

1. در Postman، Collection مورد نظر را باز کنید.
2. از منوی گزینه‌های بیشتر، مسیر More > Generate SDKs را انتخاب کنید.

در صفحه SDK می‌توانید SDK را دانلود کنید یا با گزینه Publish SDK آن را برای انتشار و اتصال آماده کنید.

مرحله ۲: اتصال SDK به repository در GitHub

بعد از تولید SDK، آن را به یک repository وصل کنید تا به‌روزرسانی‌های بعدی از مسیر PR انجام شوند.

1. در صفحه مستندات SDK، روی Publish SDK کلیک کنید.
2. گزینه Connect to GitHub را انتخاب کنید.

3. در پنجره Connect repository، provider را انتخاب کنید: GitHub یا GitHub Enterprise Server.
4. اگر لازم بود، با حساب GitHub وارد شوید.
5. organization مربوط به GitHub را از dropdown انتخاب کنید. اگر organization را نمی‌بینید، نصب بودن Postman app و دسترسی‌های خودتان را بررسی کنید.
6. repository را انتخاب یا وارد کنید. اگر repository هنوز وجود ندارد، آن را در GitHub بسازید و سپس به Postman برگردید.
7. branch را انتخاب کنید. مقدار پیش‌فرض معمولا main است. اگر repository خالی باشد، Postman اعلام می‌کند SDK در اولین sync روی main push می‌شود.
8. روی Connect کلیک کنید. بعد از اتصال، صفحه SDK وضعیت انتشار را نشان می‌دهد.

در وضعیت Published، اطلاعاتی مثل repository متصل‌شده، branch و بخش Package Managers نمایش داده می‌شود.

مرحله ۳: بررسی و merge کردن PR اولیه

بعد از اتصال، Postman یک PR اولیه در GitHub باز می‌کند. این PR معمولا شامل این موارد است:

• همه فایل‌های SDK تولیدشده.
• یک comment از Postman درباره PR.
• نتیجه بررسی امنیتی و پیشنهاد رفع مشکل، اگر vulnerability پیدا شود.

برای merge کردن PR:

1. تغییرات PR و نتیجه security scan را بررسی کنید.
2. اگر پیشنهاد امنیتی وجود دارد، آن را اعمال کنید.
3. PR را approve و سپس در branch اصلی، مثل main، merge کنید.

بعد از merge، repository شامل ساختار کامل SDK می‌شود؛ مثلا:

.github/workflows/
documentation/
examples/
scripts/
src/
.env.example
.gitignore
.manifest.json
README.md
package.json

README همان مستندات اصلی SDK را نمایش می‌دهد؛ از نصب و راه‌اندازی تا نمونه استفاده و service reference.

مرحله ۴: توزیع SDK از طریق package manager

بعد از اتصال SDK به GitHub، می‌توانید SDK را از طریق package manager مناسب زبان منتشر کنید. برای نمونه، در SDKهای TypeScript امکان انتشار در npm وجود دارد.

1. در بخش Package Managers گزینه Distribute SDKs via npm را روشن کنید.
2. token مربوط به npm را با نام NPM_TOKEN به عنوان GitHub repository secret یا organization secret اضافه کنید.
3. توکن را از npmjs بسازید. اگر 2FA فعال است، گزینه bypass برای 2FA و دسترسی Read and write برای packageها را مطابق نیاز انتخاب کنید.

بعد از merge شدن PR، GitHub Action اجرا می‌شود، package به npm push می‌شود و یک GitHub release با همان نسخه ساخته می‌شود.

مرحله ۵: فعال شدن update خودکار با تغییر Collection

بعد از اتصال repository، تغییر در Collection می‌تواند ساخت SDK جدید را فعال کند. مثلا اگر request اضافه یا حذف شود، Postman:

1. SDK جدید را بر اساس وضعیت فعلی Collection می‌سازد.
2. یک PR جدید در repository باز می‌کند.
3. در PR توضیح می‌دهد چه چیزی در Collection تغییر کرده است.

Postman نسخه SDK را هم با توجه به نوع تغییر افزایش می‌دهد. برای مثال حذف یک endpoint ممکن است نسخه را از v1.2.0 به v2.0.0 ببرد، چون breaking change محسوب می‌شود.

مرحله ۶: بررسی و merge کردن PRهای بعدی

هر PR خودکار مثل PR اولیه باید بررسی شود. بسته به سیاست سازمان، ممکن است CI check، approval یا بررسی امنیتی لازم باشد. بعد از تایید و merge، SDK در branch اصلی با وضعیت جدید Collection هماهنگ می‌شود.

مرحله ۷: مشاهده وضعیت اتصال در Postman

بعد از اتصال و merge شدن PRها، صفحه SDK در Postman این اطلاعات را نشان می‌دهد:

• repository متصل‌شده و نسخه فعلی SDK.
• وضعیت آخرین PR، مثل Open یا Merged.
• لینک View in GitHub برای رفتن به PR یا repository.
• بخش Connection status برای مشاهده PRهای ساخته‌شده.
• بخش Package Managers برای توزیع اختیاری SDK.

اگر دیگر نمی‌خواهید repository متصل باشد، از گزینه Disconnect در صفحه SDK استفاده کنید.

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