همه محصولات

نوشتن راهنمای API با هوش مصنوعی

برای هر درخواست، ورودی، پاسخ، خطا و محدودیت رو طوری مستند کنید که برنامه‌نویس بتونه بدون حدس زدن از رابط شما استفاده کنه.

نوشتن راهنمای API با هوش مصنوعی وقتی به درد می‌خوره که نمونه درخواست روی سیستم شما جواب می‌ده ولی خواننده نمی‌دونه برای مورد واقعی خودش چه چیزهایی رو باید عوض کنه. اسکیل api-documentation به ایجنت‌تون کمک می‌کنه از روی تعریف رابط و رفتاری که واقعا دیده می‌شه، مرجع قابل استفاده بسازه. مشخصات مکانیکی مثل نوع یک فیلد می‌تونن از کد بیان. توضیح اینکه نبودن اون فیلد چه اثری داره، معمولا به یک جمله روشن نیاز داره.

فرض کنید یک سرویس فهرست سفارش‌ها رو پس می‌ده. اگر فقط نمونه پاسخ موفق رو بذارید، خواننده نمی‌فهمه فهرست خالی یعنی سفارشی وجود نداره یا درخواست ناقص بوده. می‌تونید برای همین تفاوت، برای رفتن به صفحه بعد و برای حالتی که درخواست‌ها زیاد می‌شن مثال جدا بدید. هر ادعا رو با نسخه‌ای از سرویس که مستند می‌کنید بسنجید تا مثال و رفتار واقعی از هم فاصله نگیرن.

کاربردها

  • برای مستندسازی پارامترها بنویسید کدوم ورودی اجباریه و مقدار پیش‌فرض چه اثری داره.
  • یک نمونه درخواست API بسازید که از ابتدا تا پاسخ نهایی قابل دنبال کردن باشه.
  • برای توضیح خطای API، علت محتمل و کاری رو که خواننده می‌تونه انجام بده کنار هم بیارید.
  • در راهنمای صفحه‌بندی روشن کنید چطور به بخش بعدی فهرست می‌رسیم و آخر فهرست از کجا معلومه.
  • رفتار درخواست تکراری رو برای کاری که ممکنه داده‌ای رو عوض کنه با دقت توضیح بدید.

نصب و استفاده

  1. یک ایجنت، تعریف رابط یا کد مجاز و محیط آزمایشی آماده کنید. برای امتحان درخواست‌هایی که نیاز به ورود دارن از دسترسی محدود همون محیط استفاده کنید.
  2. مثلا بگید «برای گرفتن فهرست سفارش‌ها، پاسخ موفق، فهرست خالی و یک درخواست نامعتبر رو از روی رفتار همین نسخه توضیح بده».
  3. مثال رو در محیط آزمایشی اجرا کنید و مطابقت مقدارهای خروجی و متن خطا با راهنما رو بررسی کنید.

سوالات متداول

منبع

ساخته Arjun Prabhulal. نام اصلی: api-documentation، منتشرشده در GitHub با مجوز MIT.

مشاهده در GitHub