إذن، لقد سمعت الضجة حول واجهات برمجة التطبيقات - تلك الجسور السحرية التي تسمح للتطبيقات بالتواصل مع بعضها البعض - والآن تريد الغوص في الأمر، وتوثيقها مثل المحترفين، واختبارها دون جهد. نقدم لك Scalar، جوهرة مفتوحة المصدر تجعل توثيق واختبار API يبدو كأنه نزهة في الحديقة. في هذا الدليل للمبتدئين، سأساعدك على استخدام Scalar لإنشاء وثائق API مذهلة واختبار النقاط النهائية، كل ذلك بأجواء مريحة وممتعة. لا تتطلب أي سحر برمجي - فقط الفضول وجهاز لابتوب. هل أنت مستعد لتجعل لعبة API الخاصة بك تتلألأ؟ لنبدأ!
ما هو Scalar؟ رفيقك في واجهات برمجة التطبيقات
إذن، ما هو Scalar؟ إنها منصة حديثة ومفتوحة المصدر مصممة لجعل توثيق واختبار API أمرًا سهلاً. اعتبرها كدفتر أنيق يحول مواصفات API الخاصة بك (مثل ملفات OpenAPI/Swagger) إلى وثائق تفاعلية وجميلة وملعب لاختبار النقاط النهائية دون حاجة إلى أدوات إضافية. Scalar يقدم عميل API REST، ومرجع رائع، ودعم ممتاز لـ OpenAPI، كل ذلك في حزمة لا تعلن "مصممة في 2011." إنها أنيقة وصديقة للمطورين ومجانية للاستخدام.
لماذا تستخدم Scalar? إنها تحميك من الوثائق المملة المليئة بالنصوص، وتتيح لك اختبار واجهات برمجة التطبيقات مباشرة في المتصفح، وتحافظ على سعادة فريقك مع مراجع واضحة وقابلة للنقر. سواء كنت توثق واجهة برمجة تطبيقات دفع أو تختبر تطبيق قائمة المهام، فإن Scalar ستساندك. دعنا نبدأ!
تثبيت وإعداد Scalar: بدون متاعب
تشغيل Scalar أمر سهل كفطيرة - لا وصفات معقدة هنا. الوثائق في guides.scalar.com تجعل الأمر واضحًا للغاية، وسأرشدك خلال الطريقة المناسبة للمبتدئين للبدء.
الخطوة 1: اختر إعدادك
Scalar مرنة - يمكنك استخدامها كخدمة مستضافة، أو تضمينها في مشروع، أو تشغيلها محليًا. للمبتدئين، دعنا نبدأ بالأسهل: تضمين Scalar في ملف HTML أساسي للعب مع API. لا تحتاج إلى تثبيت أي شيء بعد - فقط متصفح ومحرر نصوص (مثل VS Code أو Notepad).
الخطوة 2: إنشاء ملف HTML لـ Scalar
- اصنع ملفًا: افتح محرر النصوص الخاص بك وأنشئ ملفًا جديدًا يسمى
scalar-api.html. - أضف كود Scalar: ألصق هذا المقتطف من وثائق Scalar:
<!doctype html>
<html>
<head>
<title>مرجع واجهة برمجة التطبيقات الخاصة بي</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<div id="app"></div>
<!-- تحميل Scalar -->
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
<!-- تهيئة Scalar -->
<script>
Scalar.createApiReference('#app', {
url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json',
proxyUrl: 'https://proxy.scalar.com'
})
</script>
</body>
</html>
3. احفظ وافتح: احفظ الملف، ثم انقر نقرًا مزدوجًا عليه لفتح في متصفحك (Chrome، Firefox، أو أي شيء آخر). ها هي - سترى واجهة Scalar اللامعة مع واجهة برمجة التطبيقات النموذجية (Scalar Galaxy) مُحمّلة.
تستخدم هذه الإعدادات CDN، لذا لا حاجة إلى خادم أو Node.js - مثالية لتجربة أولى. جربتها، واستغرقت أقل من دقيقتين لرؤية مرجع API يعمل. كيف تسير الأمور بالنسبة لك؟
الخطوة 3: استكشاف الواجهة
بمجرد التحميل، تعرض Scalar شريطًا جانبيًا مع نقاط API، ولوحة رئيسية مع الوثائق، ومنطقة لاختبار. انقر حولها - إنها تفاعلية! واجهة برمجة التطبيقات النموذجية Galaxy ممتعة، لكننا سنستبدلها بمواصفاتك الخاصة قريبًا. إذا كنت تريد النسخة المستضافة، اشترك في scalar.com للحصول على حساب مجاني لحفظ عملك.
إنشاء وثائق واجهة برمجة التطبيقات باستخدام Scalar
الآن، دعنا نستخدم Scalar لتوثيق API. لنفترض أنك تعمل على واجهة برمجة تطبيقات قائمة المهام - سنجعلها تبدو احترافية دون كتابة رواية.
الخطوة 1: احصل على مواصفة OpenAPI أو أنشئ واحدة
Scalar يحب ملفات OpenAPI (المعروفة أيضًا باسم Swagger) - JSON أو YAML التي تصف نقاط النهاية ومعلماتها واستجابتها. هل لديك واحدة؟ رائع! إذا لم يكن لديك، فلنبدأ بإعداد واحدة بسيطة:
- أنشئ ملفًا يسمى
todo-api.yaml:
openapi: 3.0.2
info:
title: واجهة برمجة تطبيقات قائمة المهام
version: 1.0.0
description: واجهة برمجة تطبيقات بسيطة لإدارة المهام
paths:
/tasks:
get:
summary: قائمة بجميع المهام
responses:
'200':
description: قائمة المهام
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
title:
type: string
post:
summary: إنشاء مهمة
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: string
responses:
'201':
description: المهمة تم إنشاؤها
2. احفظه في مجلد مشروعك.
هذه مواصفة بسيطة جداً، لكن Scalar ستجعلها تبدو مذهلة.
الخطوة 2: تحميل مواصفتك في Scalar
لاستخدام مواصفتك:
- استضافتها (اختياري): الآن، ضع
todo-api.yamlفي نفس المجلد معscalar-api.html. إذا كان لديك خادم ويب (مثلhttp.serverفي بايثون)، قم بتشغيل:
python -m http.server 8000
ثم ستكون مواصفتك في http://localhost:8000/todo-api.yaml.
- تحديث HTML: قم بتغيير
urlفيscalar-api.html:
Scalar.createApiReference('#app', {
url: './todo-api.yaml', // أو http://localhost:8000/todo-api.yaml
proxyUrl: 'https://proxy.scalar.com'
})
- إعادة التحميل: افتح
scalar-api.htmlمرة أخرى. ها هو - Scalar يعرض واجهة برمجة التطبيقات الخاصة بك بشكل لطيف مع شريط جانبي واضح، وتفاصيل النقاط النهائية، وأمثلة على الاستجابات.
الوثائق الآن تفاعلية - انقر فوق /tasks لرؤية تفاصيل GET وPOST. Scalar تولد نُسَخ الشيفرة في بايثون وجافا سكريبت وأكثر. لقد اندهشت من كيفية ظهور YAML المحبط الخاص بي بشكل مصقول!
الخطوة 3: تخصيص وثائقك
هل تريد لمسة إضافية؟ قم بتعديل إعدادات Scalar:
Scalar.createApiReference('#app', {
url: './todo-api.yaml',
proxyUrl: 'https://proxy.scalar.com',
theme: 'purple', // جرب 'kepler' أو 'moon'
customCss: 'body { background-color: #f0f0f0; }'
})
قم بتحديث الصفحة، وستظهر وثائقك بأجواء جديدة. يمكن للمستخدمين المستضافين حفظها على docs.scalar.com.
اختبار واجهات برمجة التطبيقات باستخدام Scalar
هنا تصبح Scalar مثيرة للإعجاب - فهي ليست فقط للوثائق. عميل API المدمج يتيح لك اختبار النقاط النهائية مباشرة في الواجهة، دون الحاجة إلى Postman.
الخطوة 1: إعداد واجهة برمجة تطبيقات قابلة للاختبار
للاختبار، تحتاج إلى API تعمل. إذا لم يكن لديك واحدة، استخدم واجهة برمجة تطبيقات اختبار عامة مثل reqres.in. قم بتحديث scalar-api.html:
Scalar.createApiReference('#app', {
url: 'https://reqres.in/api/openapi.yaml',
proxyUrl: 'https://proxy.scalar.com'
})
أعد التحميل، و Scalar يقوم بتحميل مواصفة واجهة برمجة التطبيقات ReqRes.
الخطوة 2: اختبار النقاط النهائية
- في Scalar، ابحث عن نقطة نهاية مثل
GET /api/users. - انقر فوق زر "جربه" (يبدو مثل رمز التشغيل).
- املأ المعلمات (مثل
page: 2) أو اترك القيم الافتراضية. - اضغط على "إرسال". Scalar ترسل الطلب عبر وكيلها لتجنب مشاكل CORS وتظهر الاستجابة - رمز الحالة، والرؤوس، وبيانات JSON.
جربت GET /api/users وحصلت على قائمة مستخدمين JSON مرتبة في ثوان. إذا كنت تستخدم واجهة برمجة تطبيقات قائمة المهام الخاصة بك، استضفها محليًا (مثل، باستخدام Node.js) واختبر POST /tasks مع جسم مثل {"title": "تعلم Scalar"}.
الخطوة 3: تصحيح الأخطاء والتكرار
رأيت 404؟ تحقق مرة أخرى من عنوان API الخاص بك أو الرؤوس في لوحة طلب Scalar. يظهر العميل الأخطاء بوضوح، لذلك يمكنك التعديل والمحاولة بسرعة. أضف رموز المصادقة أو معلمات الاستعلام في واجهة المستخدم - لا حاجة لأي شيفرة.
لماذا تعتبر Scalar حلمًا للمبتدئين
Scalar تتألق بالنسبة للمبتدئين لأنها:
- إعداد سهل: ملف HTML واحد، وها أنت مباشر.
- وثائق رائعة: تحول YAML الفوضوي إلى جمال يمكن النقر عليه.
- اختبار مدمج: بلا أدوات إضافية للفحوص السريعة.
- صوت المجتمع: المشاركات الإيجابية تبرز كونها "ملعب ديناميكي" لواجهات البرمجة.
مقارنةً بـ Swagger UI، تشعر Scalar بتحديث أكثر وأقل طبيعية، مع تدفق اختبار أفضل. إنها مثل ابن العم الرائع الذي يجعل كل شيء ممتعًا.
نصائح احترافية لنجاح Scalar
- ابدأ صغيرًا: استخدم مواصفة بسيطة لتتعلم تدفق Scalar.
- انضم إلى Discord: تحدث مع عشاق API في discord.gg/scalar.
- تحقق من المواصفات: ألصق YAML الخاص بك في editor.swagger.io لالتقاط الأخطاء قبل التحميل.
- انتقل إلى النسخة المستضافة: اشترك في scalar.com للتعاون والأسماء الفرعية.
الخاتمة: تبدأ مغامرتك مع واجهة برمجة التطبيقات Scalar
تهانينا - أنت الآن نجم Scalar! من إنشاء وثائق API التفاعلية إلى اختبار النقاط النهائية مثل المحترفين، لقد قمت بفتح أداة تجعل واجهات برمجة التطبيقات أقل رعبًا وأكثر متعة بكثير. جرب توثيق واجهة برمجة تطبيقات متجر حيوانات أليفة التالية أو اختبر واحدة عامة مثل JSONPlaceholder. وثائق Scalar مليئة بالمزيد من الحيل، وتصدر المجمتع صدى على Discord. ما هو مشروعك الأول API؟ لعبة؟ قاعدة بيانات مدونة؟ أوه، ولتلميع إضافي لـ API، تفضل بزيارة apidog.com.
