Swagger مستندسازی

وقتی درباره مستندسازی REST API صحبت می‌کنیم، با چند چالش مواجه می‌شویم. چطور می‌توان اطمینان حاصل کرد که مستندات به‌روز و صحیح هستند؟ دقت (Accuracy) همیشه یک چالش بزرگ است. ممکن است مستندات با کد همگام نباشند. نکته مهم دیگر، یکپارچگی (Consistency) مستندات است. در یک سازمان بزرگ ممکن است صدها REST API وجود داشته باشد. چطور می‌توان مطمئن شد که مستندات همه این APIها در قالبی یکسان ارائه شده‌اند؟ برای مستندسازی REST API دو گزینه وجود دارد: گزینه اول: نگهداری دستی مستندات می‌توانید یک فایل متنی یا HTML داشته باشید که مستندات REST API را در آن نگهداری می‌کنید. اگر مستندات را به‌صورت دستی نگهداری کنید، باید همیشه تلاش کنید آن را با کد همگام نگه دارید. گزینه دوم: تولید مستندات از روی کد می‌توان مستندات را مستقیماً از روی کد تولید کرد. قبلاً برای منبع کاربر (User Resource) کد نوشتیم. آیا می‌توانیم از همان کد برای تولید مستندات استفاده کنیم؟ در این مرحله، گزینه دوم را بررسی می‌کنیم: تولید مستندات REST API از روی کد. وقتی درباره مستندسازی REST API صحبت می‌کنیم، دو اصطلاح بسیار مهم وجود دارد که باید بدانید — مستقل از اینکه API را با چه زبانی (Java، Python، Node.js و غیره) توسعه داده‌اید. این دو اصطلاح عبارت‌اند از: Swagger OpenAPI