إنشاء توثيق Swagger API غير متصل بشكل فعّال

في سياق توثيق واجهات البرمجة (API) لتطبيق الويب الخاص بك الذي يعتمد على Spring Boot MVC في لغة البرمجة Java، يعد تكامل Springfox لتوثيق الAPI خطوة إيجابية لتحسين فهم واستخدام تلك الواجهات. ومع ذلك، تطرح استفسارك حول كيفية إنشاء توثيق Swagger API غير متصل (offline) بعض التحديات.

للبداية، يجدر بك أن تدرك أن Swagger نفسه يعتمد على ملفات JSON أو YAML لوصف توثيق الAPI. وبما أنك تسعى إلى إنشاء توثيق Swagger غير متصل في ملفات HTML بدلاً من استخدام AsciiDoc أو Markdown، فإن هذا يعني أن عليك البحث عن أداة تقوم بتحويل تلك الملفات إلى صيغة HTML.

لتحقيق هذا الهدف، يمكنك استخدام أداة تحويل ملفات Swagger JSON/YAML إلى HTML. يمكنك البحث عن أدوات مثل Swagger UI Dist، والتي تقدم إصدارًا مستقلًا يمكن تضمينه في مشروعك كملفات HTML ويعمل بشكل غير متصل. بمجرد توليد ملف Swagger JSON أو YAML لتوثيق الAPI الخاص بك، يمكنك استخدام Swagger UI Dist لتحويله إلى صفحات HTML مستقلة.

عند استخدام Swagger UI Dist، يمكنك أيضًا ضبط الروابط لتكون ذات صلة محليًا بدلاً من روابط خادم محلي. يتيح لك ذلك تصفح توثيق API دون الحاجة إلى الاتصال بالخادم. يمكنك ببساطة توفير ملفات HTML المتولدة في مشروعك وفتحها في متصفح الويب.

لاحظ أن هذا النهج يتطلب بعض الخطوات الإضافية بعد توليد ملف Swagger JSON/YAML، ولكنه يوفر القدرة على تصفح توثيق الAPI بشكل غير متصل بالإنترنت بطريقة سهلة وفعّالة.

بهذه الطريقة، يمكنك الاستفادة القصوى من وثائق Swagger الخاصة بتطبيقك دون الحاجة إلى تشغيل الخادم. إن توفير توثيق ذات قيمة وفعال يسهم في تسهيل فهم واستخدام API الخاص بك للمطورين والفرق الأخرى المعنية.

بالطبع، دعنا نعزز المعلومات حول عملية إنشاء توثيق Swagger API غير متصل بشكل أكبر.

عندما تقرر استخدام Swagger UI Dist، يمكنك تحميلها مباشرة من مستودع Swagger على GitHub. يمكنك إضافة هذا التحميل إلى مشروعك وتكامله معه. يوفر Swagger UI Dist ملفات HTML ومجلدات للموارد الضرورية مثل الأنماط والصور.

عند تحميل Swagger UI Dist، يمكنك استخدام ملف Swagger JSON أو YAML الذي يمثل توثيق API الخاص بك. يمكنك تحميل هذا الملف أو نسخه إلى نفس مجلد Swagger UI Dist.

من ثم، تحتاج إلى ضبط ملف index.html الموجود في Swagger UI Dist للإشارة إلى مكان ملف Swagger JSON أو YAML الخاص بك. يمكنك تحديد الرابط المحلي لهذا الملف بحيث يتم الوصول إليه بشكل صحيح من خلال الصفحات HTML المتولدة.

قد يكون مثالًا على جزء من ملف index.html:

htmlCopy code
url: "path/to/your/swagger.json",

تأكد من أن المسار المحدد يعكس المكان الذي قمت بتخزين فيه ملف Swagger JSON أو YAML الخاص بك داخل مشروعك.

بهذا، بمجرد تكامل Swagger UI Dist مع مشروعك وتكوينه بشكل صحيح، يمكنك فتح ملف index.html في متصفح الويب الخاص بك لتصفح توثيق API الخاص بك بشكل غير متصل بالإنترنت.

يمكنك أيضًا إجراء تعديلات إضافية في ملف index.html لتحسين تجربة المستخدم أو تكامل تخصيصات إضافية وفقًا لاحتياجات توثيق API الخاص بك.

باختصار، تكامل Swagger UI Dist يعد حلاً فعالًا لإنشاء توثيق Swagger API غير متصل بالإنترنت، مما يتيح للمطورين والفرق التفاعل مع توثيق الAPI بسهولة وفعالية.