مستندسازی API از صفر تا انتشار

یک بار در پروژه‌ای که سه تیم جداگانه روی بخش‌های مختلف کار می‌کردند، اتصال سرویس‌ها سه هفته عقب افتاد. مشکل فنی نبود؛ هیچ‌کس نمی‌دانست دقیقاً چه پارامترهایی باید بفرستد و چه انتظاری از پاسخ داشته باشد. آن روز یاد گرفتم مستندسازی API یک کار جانبی نیست؛ بخشی از خود API است. اگر با مفهوم کلی API آشنا نیستید، API چیست نقطه شروع خوبی است.

چرا مستندسازی API یک پروژه جداگانه نیست؟

در بسیاری از پروژه‌ها، مستندسازی چیزی است که در انتهای کار انجام می‌شود یا حتی کاملاً فراموش می‌شود. اما تجربه‌ام این است که مستندات، اولین مصرف‌کننده API شماست. هر توسعه‌دهنده‌ای که می‌خواهد با API شما کار کند، ابتدا مستندات را می‌خواند. اگر مستندات ناقص یا نامفهوم باشد، آن توسعه‌دهنده به تیم شما ایمیل می‌زند یا بدتر، API شما را کنار می‌گذارد و به سراغ رقیب می‌رود.

مستندسازی دو کارکرد دارد: یکی، آموزش به مصرف‌کننده جدید؛ دیگری، مرجع برای خود تیم شما در نگهداری آینده. اگر سه ماه بعد به endpointی نگاه کنید که خودتان نوشته‌اید و یادتان نیاید دقیقاً چه پارامترهایی می‌پذیرد، مستندات نجاتتان می‌دهد. برای درک اهمیت مرجع بودن، اصول طراحی REST API را ببینید.

مستندات، قرارداد بین API شما و مصرف‌کنندگان آن است. بدون این قرارداد، هر بار اتصال یک سرویس جدید، یک پروژه از صفر است.

انواع مستندسازی و انتخاب درست

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

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

OpenAPI و Swagger: استاندارد صنعت

OpenAPI یک مشخصات استاندارد برای توصیف APIهای REST است. این مشخصات که قبلاً Swagger Specification نامیده می‌شد، ساختار دقیقی برای توصیف endpointها، پارامترها، پاسخ‌ها، احراز هویت و مدل‌های داده تعریف می‌کند. Swagger مجموعه‌ای از ابزارها است که این مشخصات را می‌خواند و مستندات تعاملی، کد کلاینت و تست خودکار تولید می‌کند.

مزیت اصلی OpenAPI این است که مستندات در قالب یک فایل YAML یا JSON نگه داشته می‌شود و می‌تواند در CI/CD بررسی و به‌روز شود. اگر می‌خواهید تفاوت این فرمت‌ها را بفهمید، JSON چیست و چگونه داده‌ها را ساختاردهی می‌کند و YAML را ساده یاد بگیرید پیش‌نیازهای مفیدی هستند. راهنمای عملی استفاده از Swagger در مستندسازی REST API با Swagger آمده است.

یک نکته عملی که در پروژه‌ها به کارم آمده: از همان روز اول، فایل OpenAPI را بخشی از مخزن کد کنید. با این کار، تغییرات API و مستندات در یک کامیت اتفاق می‌افتند و از هم جدا نمی‌شوند. برای مدیریت مخزن کد، گیت در توسعه وردپرس راهنمای کاربردی دارد.

ساختار یک مستندات حرفه‌ای

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

بخش چهارم، مرجع endpointها که پرحجم‌ترین بخش است و برای هر endpoint پارامترها، پاسخ‌ها و کدهای وضعیت را توصیف می‌کند. بخش پنجم، مدل‌های داده که ساختار اشیاء پرکاربرد را نشان می‌دهد. بخش ششم، کدهای خطا و معانی آن‌ها. بخش هفتم، راهنمای نسخه‌بندی و تغییرات جدید. برای درک ساختار endpointها، REST از مفاهیم پایه تا طراحی حرفه‌ای راهنمای خوبی است.

در مرجع احراز هویت، باید هم روش‌های مختلف و هم مثال‌های دقیق بیاید. راهنمای کامل احراز هویت در احراز هویت در API آمده و برای بخش امنیتی، امنیت API و بهترین روش‌ها نکات کاربردی دارد.

مثال کد: چیزی که کاربران واقعاً می‌خواهند

در مستندات API، مثال‌های کد بیشتر از توضیحات فنی خوانده می‌شوند. تجربه‌ام این است که اگر مثال‌ها در چند زبان رایج باشند - مثلاً curl، JavaScript، PHP و Python - درصد بیشتری از توسعه‌دهندگان بدون کمک اضافه می‌توانند کار کنند. مثال curl برای تست سریع، مثال JavaScript برای مرورگر و Node.js، و مثال Python برای اسکریپت‌نویسی.

هر مثال باید سه ویژگی داشته باشد. اول، قابل کپی و اجرا در محیط واقعی باشد. دوم، پارامترهای واقعی داشته باشد نه placeholderهای بی‌معنی. سوم، خروجی واقعی و کامل را نشان دهد. مثال‌های ناقص، بدتر از نداشتن مثال هستند چون امید کاذب می‌سازند. برای ساخت API در PHP و پایتون، ساخت API با PHP و ساخت REST API با پایتون راهنمای کاملی دارند.

در مستندات تعاملی، امکانی که کاربر بتواند API را مستقیماً از صفحه مستندات تست کند، ارزش زیادی دارد. Swagger UI و ReDoc هر دو این قابلیت را دارند. برای تست پیشرفته‌تر، تست REST API با Postman و تست API راهنمای مفیدی هستند.

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

مستندات API یک سند زنده است. هر بار که API تغییر می‌کند، مستندات باید با آن همگام شود. بی‌توجهی به این همگامی، به مستندات اشتباه و اعتماد از دست رفته منجر می‌شود. بهترین روش، نسخه‌بندی مستندات است: مستندات هر نسخه از API جدا نگه داشته شود و نسخه‌های قدیمی برای مدت مشخص در دسترس باشند.

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

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

خودکارسازی مستندات در CI/CD

مستندات دستی که همگام با کد نگه داشته نمی‌شود، خیلی زود کهنه می‌شود. خودکارسازی مستندات در CI/CD چند فایده دارد: اول، هر تغییر در کد باعث به‌روزرسانی مستندات می‌شود. دوم، اگر مستندات با کد همگام نباشد، CI می‌تواند خطا بدهد و مانع انتشار شود. سوم، همیشه نسخه‌ای منتشرشده و به‌روز از مستندات وجود دارد.

راه‌اندازی CI/CD برای پروژه‌های وردپرسی در CI/CD برای پروژه‌های وردپرسی توضیح داده شده است. برای پروژه‌های Node.js و پایتون، ابزارهای استاندارد مثل GitHub Actions و GitLab CI این کار را ساده می‌کنند. برای مدیریت مخزن، دستورات پرکاربرد Git راهنمای کاربردی است.

یک الگوی عملی که در پروژه‌ها به کارم آمده: هر تغییر در فایل OpenAPI باید در pull request بازبینی شود. این کار باعث می‌شود مستندات هم مثل کد جدی گرفته شوند. برای آشنایی با pull request، Pull Request در GitHub راهنمای کاملی دارد. برای مدیریت شاخه‌ها در فرآیند توسعه، برنچ در Git نکات مهمی ارائه می‌دهد.

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

پرسش‌های پرتکرار درباره مستندسازی API

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

چه ابزاری برای مستندسازی پیشنهاد می‌کنید؟ برای APIهای REST، OpenAPI به‌همراه Swagger UI یا ReDoc استاندارد صنعت است. برای GraphQL، GraphiQL و Apollo Studio. برای مستندات عمومی، ترکیبی از ابزارهای تولید خودکار و یک لایه دستی.

چگونه مستندات را همگام با کد نگه دارم؟ با خودکارسازی در CI/CD. اگر از یک فایل OpenAPI استفاده می‌کنید، تغییرات API و مستندات باید در یک pull request اتفاق بیفتند.

آیا مستندات عمومی باید همه endpointها را پوشش دهد؟ فقط endpointهایی که برای مصرف‌کنندگان عمومی مفید هستند. endpointهای داخلی باید در مستندات داخلی جدا باشند.

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

برای اتصال ووکامرس به سرویس‌های خارجی که مستندات API مهمی دارد، اتصال ووکامرس به API های خارجی راهنمای کاملی است. برای REST API وردپرس، استفاده از REST API در وردپرس و REST API در وردپرس را ببینید.

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

آنچه از پروژه‌های واقعی یاد گرفتم

سه چیز بعد از سال‌ها کار با مستندسازی API در ذهنم جا افتاده. اول، مستندات را از روز اول بنویسید، نه در انتهای پروژه. دوم، خودکارسازی کنید تا همگامی با کد حفظ شود. سوم، مستندات را مثل کد بازبینی کنید. برای آشنایی با ابزارهای مدیریت پروژه که در این مسیر مفیدند، Jira برای مدیریت پروژه توسعه و Visual Studio Code را ببینید. برای پیاده‌سازی ساختاری، استفاده از REST API در وردپرس و ساخت REST API با پایتون را مطالعه کنید.

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