مستندات API؛ چرا همیشه قدیمی می‌شود و چطور نشود

مستندات API معمولاً یک بار نوشته می‌شود و بعد آرام‌آرام دروغ می‌شود. سه ماه بعد، فیلدی که در سند هست دیگر وجود ندارد، فیلدی که اضافه شده هیچ‌جا نیامده، و دولوپر فرانت‌اند به‌جای خواندن سند، از تیم بک‌اند می‌پرسد. این راهنما می‌گوید چرا این اتفاق ساختاری است نه انضباطی، تفاوت OpenAPI و Swagger و Postman را روشن می‌کند، و نشان می‌دهد مستنداتی که نمی‌تواند کهنه شود چه شکلی است.

چرا مستندات همیشه قدیمی می‌شود

چون مستندات و کد دو منبع جدا هستند. تغییر در یکی، دیگری را به‌روز نمی‌کند؛ فقط آدم‌ها این کار را می‌کنند و آدم‌ها زیر فشار تحویل، همیشه همین را جا می‌اندازند.

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

OpenAPI، Swagger و Postman چه فرقی دارند؟

این سه اسم مدام جای هم به کار می‌روند و سه چیز متفاوت‌اند:

نکته‌ی عملی: OpenAPI اصل ماجراست و بقیه مصرف‌کننده‌اش‌اند. اگر فایل OpenAPI درست و به‌روز داشته باشید، هم Swagger UI دارید، هم کالکشن Postman، هم امکان تولید خودکار کلاینت برای زبان‌های مختلف.

یک مستند خوب چه چیزهایی دارد

فراتر از فهرست اندپوینت‌ها، چهار چیز است که نبودشان بیشترین وقت را می‌گیرد:

1. قالب خطا، یک‌بار و دقیق. دولوپر باید بداند خطا چه شکلی برمی‌گردد و چطور تشخیصش بدهد. قالب استاندارد (RFC 7807) یعنی لازم نیست برای هر اندپوینت جدا حدس بزند.
2. صفحه‌بندی، صریح. «چطور صفحه‌ی بعد را بگیرم» سؤالی است که در نبودش، همه offset را حدس می‌زنند و روی داده‌ی متحرک نتیجه‌ی غلط می‌گیرند.
3. احراز هویت، با مثال واقعی. هدر دقیق، نه توضیح کلی.
4. نمونه‌ی پاسخ واقعی. نمونه‌ای که از خود مدل داده ساخته شده، نه نمونه‌ای که کسی دستی نوشته و دو نسخه عقب است.

مستنداتی که نمی‌تواند کهنه شود

در فیکارو مدل داده منبع حقیقت است: همان تعریفی که رفتار API را می‌سازد، مستندات را هم می‌سازد. یعنی فیلدی که اضافه می‌کنید همان لحظه در سند هست و فیلدی که حذف می‌کنید از سند می‌رود — چون دو منبع جدا وجود ندارد که از هم فاصله بگیرند.

چیزی که خودکار همراه پروژه می‌آید:

• فایل OpenAPI پروژه، به‌روز
• Swagger UI برای خواندن و تست در مرورگر
• کالکشن Postman برای تحویل به تیم
• راهنماهای cookbook برای کارهای متداول

و در عمل یعنی این درخواست، همان چیزی است که در سند نوشته شده:

curl "https://api.fikaro.ir/my-shop/v1/product?filter[status]=active&sort=-created_at&limit=20" \
  -H "Authorization: Bearer apck_..."

{
  "data": [{ "id": "0192f3...", "status": "active" }],
  "pagination": { "limit": 20, "nextCursor": "eyJ..." }
}

nextCursor همان جواب سؤال صفحه‌بندی است: مقدارش را در درخواست بعدی می‌فرستید. صفحه‌بندی مبتنی بر cursor روی داده‌ای که مدام رکورد تازه می‌گیرد، رکورد جا نمی‌اندازد و تکراری هم نمی‌دهد — کاری که با شماره‌ی صفحه نمی‌شود.

تحویل به تیم و مصرف از کلاینت

اگر کسی قرار است به API شما وصل شود، دو چیز بدهید: آدرس Swagger پروژه و کالکشن Postman. با همین دو تا، دولوپر بدون پرسیدن حتی یک سؤال شروع می‌کند. برای مصرف از کد هم خروجی‌ها و SDK کلاینت‌های آماده می‌دهد و اتصال فرانت‌اند به API می‌گوید لایه‌ی ارتباط را چطور بنویسید.

اگر هنوز API ندارید و از اینجا شروع می‌کنید، ساخت API بدون کدنویسی کل مسیر را دارد و وب سرویس چیست مفاهیم پایه را.

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

تفاوت OpenAPI و Swagger چیست؟

OpenAPI استاندارد توصیف API است — یک فایل JSON یا YAML که ماشین می‌خواند. Swagger UI رابط کاربری‌ای است که همان فایل را در مرورگر نمایش می‌دهد و امکان تست می‌دهد. یعنی OpenAPI محتواست و Swagger یکی از راه‌های دیدنش.

چطور کاری کنم مستندات API عقب نیفتد؟

با انضباط تیمی نمی‌شود؛ باید مستندات از همان چیزی مشتق شود که رفتار API را تعیین می‌کند. معیار سنجش ساده است: اگر فیلدی اضافه کنید و هیچ کار دیگری نکنید، سند باید خودش عوض شود.

برای تحویل API به دولوپر فرانت‌اند چه چیزی بفرستم؟

آدرس Swagger پروژه و کالکشن Postman. با این دو، دولوپر اندپوینت‌ها، قالب خطا، احراز هویت و صفحه‌بندی را می‌بیند و بدون پرسیدن شروع می‌کند.

صفحه‌بندی cursor چه فرقی با شماره‌ی صفحه دارد؟

شماره‌ی صفحه روی داده‌ای که مدام رکورد تازه می‌گیرد، رکورد جا می‌اندازد یا تکراری نشان می‌دهد، چون مبنایش جایگاه است. cursor نشانگر آخرین رکورد خوانده‌شده را می‌برد، پس نتیجه‌اش با تغییر داده به‌هم نمی‌ریزد.