نوشتن مستندات API در Postman با هوش مصنوعی
از روی مشخصات سرویس و درخواستهای موجود، راهنمایی بنویسید که ورودی، سطح دسترسی، پاسخ موفق و خطاهای مهم را برای برنامهنویس بعدی روشن کند.
نوشتن مستندات API در Postman با هوش مصنوعی وقتی ارزش دارد که درخواست نمونه برای تیم شما کار میکند اما برنامهنویس تازه نمیداند کدام فیلد ضروری است یا در صورت خطا باید دوباره تلاش کند. اسکیل api-documentation کمک میکند ایجنتتون از روی مشخصات تاییدشده و مجموعه درخواستهای فعلی، نکتههایی را پیدا کند که واقعا روی تصمیم استفادهکننده اثر میگذارند. هر تضمینی هم باید به قرارداد سرویس یا رفتار بررسیشده وصل باشد.
مثلا ممکن است مشخصات فنی تازهای برای بخش سفارش منتشر شده باشد ولی مجموعه قدیمی چند نمونه خطای کاربردی داشته باشد. ساخت مجموعه از روی مشخصات جدید دلیل خوبی برای پاک کردن آن نمونهها نیست. میتوانید از ایجنت بخواهید ابتدا تفاوت را نشان بدهد و بعد درباره نگه داشتن توضیحها، نمونهها و بررسیهایی که تیم از قبل نوشته تصمیم بگیرید.
کاربردها
- برای هر نمونه پاسخ API، وضعیت و فیلدهایی را نشان بدهید که خواننده برای ادامه کار نیاز دارد و از داده واقعی مشتری در مثال استفاده نکنید.
- در مستندسازی خطا، موارد قابل تلاش دوباره را از خطاهایی که نیاز به اصلاح ورودی دارند جدا کنید، اگر قرارداد سرویس چنین تفاوتی را مشخص کرده است.
- وقتی مشخصات OpenAPI منبع اصلی است، مجموعه تولیدشده را کنار مجموعه فعلی بگذارید و پیش از جایگزینی نمونههای مهم را مقایسه کنید.
- راهنمای احراز هویت را طوری بنویسید که سطح دسترسی لازم معلوم باشد و کلید واقعی در متن یا درخواست نمونه باقی نماند.
- محل تحویل را بر اساس مخاطب انتخاب کنید تا مرور داخل تیم با انتشار عمومی راهنما اشتباه نشود.
نصب و استفاده
- مجموعه مجاز Postman یا مشخصات سرویس و نمونههای ساختگی آماده کنید. برای کار محلی ابزار رسمی لازم است و برای انتشار باید مجوز فضای مقصد را داشته باشید.
- مثلا بگویید «راهنمای ثبت سفارش را کامل کن. پاسخ موفق و یک خطای ورودی بگذار و پیش از جایگزین کردن مجموعه، تفاوت با نسخه قبلی را نشان بده.»
- نمونهها را بخوانید و قبل از در دسترس گذاشتن راهنما، مخاطب و اطلاعاتی را که او میتواند ببیند مشخص کنید.
سوالات متداول
منبع
ساخته Postman. نام اصلی: api-documentation، منتشرشده در GitHub با مجوز Apache-2.0.
مشاهده در GitHub