توثيق الواجهات البرمجية باستخدام Swagger/OpenAPI

لكل واجهة برمجية توثيق. والسؤال الوحيد هو: أين يعيش هذا التوثيق، ومنذ متى أصبح خاطئًا؟ ملف Word على مجلد مشترك في الشبكة، أو صفحة ويكي، أو مجموعة Postman صدّرها مطوّر غادر الفريق منذ مدة، أو سلسلة نقاش انتهى فيها أحدهم إلى كتابة المثال الذي يعمل فعلًا: هذه هي الأشكال الأربعة التي يتخذها التوثيق تلقائيًا، وكلها تشترك في العيب نفسه. فهي تُكتب بمعزل عن الكود، ولذلك تنحرف عنه منذ أول commit يلي كتابتها.

وثمن هذا الانحراف يدفعه الآخرون. فمطوّر تطبيق الجوال الذي يرسل حقلًا أُعيدت تسميته الأسبوع الماضي يحصل على خطأ 400 لا يفهمه، فيكتب رسالة وينتظر الرد، ويضيع منه نصف يوم. اضرب ذلك في عدد العملاء وفي وتيرة التعديلات.

يقدّم OpenAPI حلًّا بنيويًا بدل الحل القائم على الانضباط: فوصف الواجهة يُنتَج من الكود نفسه. المسارات تأتي من @RequestMapping، والمخططات من كائنات DTO، والقيود من تعليقات التحقق التوضيحية. وإعادة تسمية حقل تغيّر التوثيق في الـ commit نفسه، دون أن يحتاج أحد إلى التفكير في ذلك. أما ما يبقى للكتابة اليدوية فهو النوايا: ما تفعله نقطة النهاية، ولماذا قد تفشل، وما الذي يجب أن يرسله العميل؛ أي بالضبط ما لا يستطيع الكود استنتاجه.

يوثّق هذا الدرس biblio-api باستخدام springdoc-openapi، ويعرض واجهة Swagger، ويعالج نقطتين تُكتشفان دائمًا بعد فوات الأوان: توثيق أخطاء ProblemDetail، وجعل نقاط النهاية المحمية قابلة للتجربة من المتصفح.