📎در باب API Documentation و Discoverability

📎در باب API Documentation و Discoverability

بیاین فرض کنیم REST API ماه مثل منو رستورانه؛ API Documentation همون فهرستیه که جزئیات هر غذا (یا توی این مورد، هر endpoint) رو شرح می‌ده، مثلاً ورودی‌ها، خروجی‌ها، خطاهای احتمالی و ...

از طرفی، Discoverability یعنی این که چطور می‌تونیم به راحتی بفهمیم کدوم endpoint ها وجود دارن و چه امکاناتی رو فراهم می‌کنن. این باعث میشه که توسعه‌دهنده‌ سریع‌تر بتونه از API استفاده کنه و به روزرسانی‌ها رو در زمان مناسب متوجه بشه. این روز‌ها هم که به جز توی پروژه‌ها و تیم‌های کوچیک، افراد و حتی تیم‌هایی که API رو توسعه می‌دن و API رو مصرف می‌کنن؛ از هم جداست. پس باید به فکر اون بیچاره‌ای که می‌خواد API رو سمت خودش استفاده کنه هم باشیم؛ هم Documentation و هم Discoverability رو پاس بداریم (به فکر اعصاب افراد و وقت خودمون باشیم)

⚙️ مفهوم API Documentation؟

- راهنمای ورودی و خروجی: چه پارامترهایی نیاز دارین و خروجی چجوری خواهد بود. خصوصا وقتی آبجکت‌های پیجیده و بزرگ تبادل می‌شه، این موضوع مهم خواهد بود.

- مثال‌های کاربردی: نشون دادن نمونه درخواست و پاسخ.

- خطاها: توضیح اینکه چه خطاهایی ممکنه پیش بیاد و چطور می‌تونین اونا رو مدیریت کنین.

⚙️ مفهوم Discoverability (قابلیت کشف API)

وقتی از Discoverability صحبت می‌کنیم، منظورمون اینه که API هایمون به راحتی قابل دسترسی و شناسایی باشه. این یعنی:

- سازماندهی مناسب: ساختار واضح و منظم برای endpointها.

- استفاده از استانداردها: مثل OpenAPI Specification که باعث میشه ابزارهای مختلف بتونن مستندات شما رو بخونن و حتی تست کنند.

- امکانات جستجو: مثلاً داشبوردهایی که امکان فیلتر کردن و جستجو در مستندات رو فراهم می‌کنن.

نگاهی به اکوسیستم:

استاندارد OpenAPI Specification: یه استاندارد باز برای توصیف APIها که اکثر ابزارهای مدرن از اون استفاده می‌کنن. و تقریبا مهم‌ترین استاندارد این حوزه است.

ابزارهای Swagger UI / Swagger Editor: ابزاری برای نمایش مستندات API به صورت تعاملی (از OpenAPI به خوبی پشتیبانی می‌کنه)

ابزار Redoc: یه ابزار خوب برای ارائه مستندات API سازگار با OpenAPI به صورت آنلاین.

پلتفرم Postman: علاوه بر تست API، مستندات خوبی از APIها ایجاد می‌کنه، فضای مناسبی برای اشتراک API + Doc + Test + ... برای تیم‌ها و شرکت‌ها داره و کلا یک پلتفرم برای API سازمان است و محدود به یه تولز برای GET و POST نیست... پیشرو این داستانه و بعدتر Insomnia و ابزارهای مشابه هم با قوت و کاستی‌های خاص خودشون اومدن

* ابزارهایی مثل API Blueprint هم بودن که اهمیت یا استقبال زیادی نداشتن و به حاشیه رونده شدن.

برای گو: swaggo و go-swagger

برای پایتون: خود FastAPI به صورت ضمنی

برای دات‌نت: دقت کنید که دات‌نت در نسخه ۹ به بعد هم کمافی‌السابق OpenAPI رو پشتیبانی می‌کنه، بحث‌ها سر جایگزینی اون UI سابقی است که Swagger UI تولید می‌کرد. و جایگزین‌هایی برای تولید Swagger UI و Redoc و Scaler ارائه شده.

💬 نظر؟ تجربه؟ سوال؟

📌 درضمن، به‌زودی شیوه ارائه مطالب تغییر می‌کنه، توی وبلاگ خواهم نوشت که امکانات بهتری برای پیدا کردن مطالب و دسته‌بندی‌ها و تجربه مطالعه داره و اینجا اعلانش رو قرار خواهم داد. برای همین هم این کد کوچیک رو نوشتم تا از مطالب کانال تلگرامی خروجی Markdown بگیرم که سریع‌تر مطالب فعلی رو منتقل کنم... اگر ایده یا پیشنهاد یا نقدی دارید خوشحال می‌شم.