وقتی در Postman یک Collection می‌سازید، Postman برای آن مستندات پایه ایجاد می‌کند؛ شامل جزئیات درخواست‌ها و نمونه کد در زبان‌های مختلف. در افزونه VS Code می‌توانید توضیحات، لینک، تصویر و ویدیو اضافه کنید تا مستندات برای مصرف‌کنندگان API قابل فهم‌تر شود.
نوشتن مستندات
اعضایی که role آن‌ها Editor است می‌توانند برای Collection، folder و request توضیح اضافه کنند. این توضیح را می‌توانید با editor تصویری Postman یا با Markdown بنویسید.
افزودن توضیح به Collection یا folder
- بخش Collections را باز کنید و Collection یا folder را انتخاب کنید.
- در تب Overview توضیح را وارد کنید.
- بیرون editor کلیک کنید تا توضیح ذخیره شود.
افزودن توضیح به request
- بخش Collections را باز کنید و request موردنظر را انتخاب کنید.
- در بالا سمت راست روی View Documentation کلیک کنید.
- توضیح request را وارد کنید.
- بیرون editor کلیک کنید تا تغییرات ذخیره شود.
دیدن مستندات کامل Collection
مستندات کامل Collection شامل توضیح هر request، method و URL، authorization، headerها، parameterها، نمونه کد و response exampleهاست.
- بخش Collections را باز کنید و Collection را انتخاب کنید.
- در تب Overview روی View complete documentation کلیک کنید.
- مستندات کامل در یک تب جدید داخل افزونه باز می‌شود.
تغییر زبان نمونه کد
در نمای کامل مستندات، تب Language را باز کنید و زبان موردنظر را انتخاب کنید. مستندات نمونه کد هر درخواست را با زبان انتخاب‌شده به‌روزرسانی می‌کند.
نکته عملی
برای هر request حداقل هدف درخواست، ورودی‌های لازم، نمونه پاسخ موفق و خطاهای رایج را توضیح دهید. این کار استفاده از Collection را برای هم‌تیمی‌ها و مصرف‌کنندگان API ساده‌تر می‌کند.
منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.