هل تحتاج إلى مساعدة في تطوير وتوثيق واجهات برمجة التطبيقات لمشاريع كبيرة أو معقدة؟ لا تقلق! لدينا الحل المناسب لك - مواصفات OpenAPI (المعروفة سابقًا بمواصفات Swagger). هذه المعيار المجاني ومفتوح المصدر يجعل تطوير واجهات برمجة التطبيقات وتوثيقها أمرًا سهلاً! مع OpenAPI، يمكنك بسهولة إنشاء وتوثيق واجهات برمجة التطبيقات باستخدام تنسيق موحد سهل الفهم.
وفر الوقت في محاولة فهم تطوير وتوثيق واجهات برمجة التطبيقات المعقدة. دعنا نساعدك في تبسيط العملية باستخدام OpenAPI!
ما هي مواصفات OpenAPI (OAS)
OpenAPI هي مواصفات تحدد هيكل واجهة برمجة تطبيقات RESTful وتصف قدراتها. توفر مواصفات OpenAPI طريقة موحدة لتوثيق والتفاعل مع واجهات برمجة التطبيقات، مما يتيح للمطورين اكتشاف وفهم كيفية عملها بكفاءة. تستخدم واجهات برمجة التطبيقات RESTful بروتوكول HTTP لنقل البيانات، مما يسهل على المنصات والأنظمة أن تكتب بلغات برمجة مختلفة للتواصل.
مع OpenAPI، لا تحتاج إلى الوصول إلى كود المصدر أو فحص حركة المرور الشبكية لفهم كيفية عمل واجهة برمجة التطبيقات. توفر تعريف واجهة برمجة التطبيقات نفسها كل المعلومات التي تحتاجها.
تنسيق OpenAPI
الإصدار الأخير من OpenAPI هو 3.0. يمكن كتابة تعريفات OpenAPI بتنسيق JSON أو YAML. يمثّل JSON البيانات باستخدام أزواج المفتاح-القيمة بدلاً من كتابة وصف واجهة برمجة التطبيقات الطويل واتباع هيكل OpenAPI. يجعل ذلك من السهل فهم قدرات واجهة برمجة التطبيقات، حتى إذا لم يكن لديك وصول إلى كود المصدر أو الوثائق.
مثال لمواصفات OpenAPI 3.0 بتنسيق JSON:
{
"openapi": "3.0.0",
"info": {
"title": "عنوان واجهة برمجة التطبيقات",
"description": "وصف واجهة برمجة التطبيقات",
"version": "1.0.0"
}
}
}
على سبيل المثال، في الوثائق التقليدية، ستكتب قسمًا منفصلًا لكل طريقة من طرق واجهة برمجة التطبيقات، موضحًا ما تقوم به وكيفية استخدامها. تتخذ OpenAPI نهجًا مختلفًا من خلال تنظيم هذه المعلومات في سلسلة من أزواج المفتاح-القيمة. تحتوي كل طريقة على مجموعة من الخصائص التي تصفها، بما في ذلك معلمات الطلب وأكواد الاستجابة.
بينما يعد JSON هو التنسيق القياسي لـ OpenAPI، يمكنك أيضًا استخدام YAML، وهي لغة ترميز أبسط. يجعل ذلك من الأسهل إنشاء وتحرير وثائق OpenAPI.
openapi: 3.0.0
info:
title: عنوان واجهة برمجة التطبيقات
description: وصف واجهة برمجة التطبيقات
version: 1.0.0
إذًا ها هو - أساسيات OpenAPI. قد يبدو الأمر تقنيًا قليلاً في البداية، ولكن بمجرد أن تتقن الأمر، ستتساءل كيف كنت تعيش بدونها.
تستخدم مواصفات OpenAPI أنواع بيانات JSON المعرفة في مواصفات JSON Schema. تشمل هذه الأنواع عددًا صحيحًا، وأرقامًا، وقيم بولينية، وسلاسل نصية. يمكنك أيضًا تعديل تنسيق هذه الأنواع باستخدام خاصية 'format'، مثل int32، int64، float، double، binary، data، date-time، وpassword format. كما تسمح OpenAPI باستخدام نماذج (أشياء) تعرف وفقًا لمواصفة JSON كأشياء مخطط.
هيكل OpenAPI
مواصفات OpenAPI هي وثيقة تصف هيكل وسلوك واجهات برمجة التطبيقات REST. دعونا نستعرض وثيقة OpenAPI بعمق أكثر.
تحتوي وثيقة OpenAPI على تنسيق هيكلي يتكون من كائنات أو مصفوفات من الكائنات التي تجمع أزواج المفتاح-القيمة المتعلقة ببعضها. تحتوي المجموعة الأولى من الأقواس {} في وثيقة OpenAPI على جميع الخصائص وتسمى "كائن الوثيقة". بينما هناك بعض المرونة، يجب أن تتقيد وثائق OpenAPI بهيكل أساسي. بعض الأقسام ذات المستوى العالي إلزامية، بينما الآخرون اختياريون، مما يسمح بتنوع مواصفات OpenAPI عبر واجهات برمجة التطبيقات المختلفة.
قد تحتوي وثيقة OpenAPI على الأقسام التالية:
- OpenAPI: تتطلب واجهة برمجة التطبيقات تحديد إصدار OpenAPI لتمكين الأدوات من تحليل مواصفات OpenAPI وتوليد الوثائق.
- Info: تحتوي هذه الحقل على بيانات وصفية حول واجهة برمجة التطبيقات، مثل عنوانها، ووصفها، وإصدارها. يمكن للأدوات المختلفة الاستفادة من هذه المعلومات.
- Servers: يتكون هذا الحقل في مواصفات OpenAPI من مصفوفة من كائنات الخادم، تحتوي كل منها على عنوان URL لمضيف الخادم ووصف قصير للخادم. توفر هذه المعلومات تفاصيل الاتصال التي يمكنك استخدامها للتفاعل مع الخادم.
- Paths: يحتوي هذا الكائن على المسارات النسبية لنقاط النهاية المنفصلة لواجهة برمجة التطبيقات. يتضمن كل مسار العمليات المتاحة للتفاعل مع واجهة برمجة التطبيقات، مثل POST و GET و PUT أو DELETE.
- Components: هذا الحقل في مواصفات OpenAPI هو كائن يحتوي على مخططات قابلة لإعادة الاستخدام لأجسام الطلبات، ومخططات الاستجابة، وخطط الأمان. يمكن الإشارة إلى هذه المخططات في جميع أنحاء المواصفة باستخدام علامة $ref، خاصة في كائن المسار.
- Security: كائن يعلن عن نوع خطة الأمان التي تفوض الطلبات. يتم تعريف كائن الأمان عالميًا أو يتم تجاوزها بواسطة العمليات الفردية.
- Tags: كائن يحتوي على بيانات وصفية تحدد ترتيب عرض موارد واجهة برمجة التطبيقات في الوثائق.
- ExternalDocs: كائن يرتبط بوثائق إضافية، مثل أدلة المستخدم.
إليك القالب الأساسي لوثيقة OpenAPI مع الحقول المطلوبة بتنسيق YAMLJSON.
طلب POST
تم تعريف نقطة النهاية التالية لطلب POST لتحميل صورة لحيوان أليف.
openapi: 3.0.3
info:
title: متجر الحيوانات الأليفة Swagger - OpenAPI 3.0
version: 1.0.11
servers:
- url: https://petstore3.swagger.io/api/v3
tags:
- name: حيوان أليف
description: كل شيء عن حيواناتك الأليفة
paths:
/pet/{petId}/uploadImage:
post:
tags:
- حيوان أليف
summary: تحميل صورة
description: ''
operationId: uploadFile
parameters:
- name: petId
in: path
description: هوية الحيوان الأليف الذي سيتم تحديثه
required: true
schema:
type: integer
format: int64
- name: additionalMetadata
in: query
description: بيانات وصفية إضافية
required: false
schema:
type: string
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: عملية ناجحة
يمكنك تنفيذ مقتطف الكود أعلاه في https://editor.swagger.io/. ستكون النتيجة كما يلي.
يبدأ مقتطف الكود بتقديم معلومات أساسية حول واجهة برمجة التطبيقات، مثل عنوانها وإصدارها. كما يحدد عنوان URL الأساسي لخادم واجهة برمجة التطبيقات.
تحدد قسم التسميات علامة تسمى "حيوان أليف" تجمع جميع نقاط النهاية المتعلقة بالحيوانات الأليفة. يحتوي قسم المسارات على تعريف لنقطة النهاية /pet/{petId}/uploadImage.
تدعم نقطة النهاية /pet/{petId}/uploadImage طريقة POST لتحميل صورة لحيوان أليف. يحدد قسم المعلمات معاملتين، "petId" و "additionalMetadata،" التي تحدد هوية الحيوان الأليف الذي يتم تحديثه وأي بيانات وصفية إضافية للصورة المحملة، على التوالي.
يحدد قسم نص الطلب هيكل جسم الطلب، والذي من المتوقع أن يكون بتنسيق ثنائي. يحدد قسم الاستجابات رمز استجابة واحد، 200، مما يشير إلى عملية ناجحة.
ما هي فوائد OpenAPI؟
تقدم مواصفات OpenAPI العديد من الفوائد للمطورين الذين يبنون ويجسدون واجهات برمجة التطبيقات.
تبسط مواصفات OpenAPI تطوير واجهة برمجة التطبيقات من خلال تحسين التعاون، والتناسق، وتوليد الكود، والتحقق، والأدوات. طريقة موحدة وشفافة لوصف واجهات برمجة التطبيقات تبسط قدرة الفرق على العمل معًا بشكل فعال مع ضمان التناسق في توثيق واجهات برمجة التطبيقات.
يمكن للمطورين توليد الكود لواجهات برمجة التطبيقات بلغات برمجة متعددة، مع الحفاظ على التناسق عبر اللغات. تعد الملفات الوثائقية التي تم إنشاؤها موثوقة ومتناسقة بينما توفر الوقت للمطورين.
تساعد أدوات التحقق في ضمان التوافق ومنع الأخطاء، في حين أن النظام البيئي الغني من الأدوات يبسط عملية تطوير واجهة برمجة التطبيقات بشكل كامل. تقلل مواصفات OpenAPI الأخطاء وتحسن جودة المشاريع البرمجية الناتجة.
كيفية إنشاء مواصفات OpenAPI
ولكن ماذا لو كنت تفضل تجنب كتابة الكود يدويًا؟ لا تقلق فنحن هنا للمساعدة! Apidog هي أداة تجعل العمل مع مواصفات OpenAPI أمرًا سهلاً. إنها منصة سحابية تبسط تصميم، واختبار، ونشر واجهات برمجة التطبيقات. مع ذلك، يمكن للمطورين إنشاء وتحرير مواصفات OpenAPI باستخدام محرر بصري سهل الاستخدام.
تشمل Apidog أيضًا اختبارات مدمجة تسمح للمطورين باختبار واجهات برمجة التطبيقات مباشرة من المنصة. توفر منصة سوق للواجهات البرمجية حيث يمكن للمطورين اكتشاف واستخدام واجهات البرمجة المسبقة من مطورين آخرين. مع ذلك، يمكنك بسرعة إضافة مسارات، ومعلمات، واستجابات إلى واجهات برمجة التطبيقات الخاصة بك باستخدام واجهة سهلة الاستخدام.
أفضل جزء؟ Apidog تولد الوثائق تلقائيًا. بضع نقرات فقط، يمكنك إنشاء وثائق رائعة لواجهة برمجة التطبيقات الخاصة بك بناءً على مواصفاتها OpenAPI. تشمل الوثائق معلومات حول كل نقطة نهاية، بما في ذلك معلماتها، واستجاباتها، والأمثلة.
دعنا نلقي نظرة خطوة بخطوة على كيفية القيام بذلك. إليك عملية خطوة بخطوة لاستيراد ملف مواصفات OpenAPI إلى Apidog:
الخطوة 1. افتح موقع Apidog
أولاً، افتح موقع Apidog في متصفح الويب الخاص بك. يمكنك الوصول إليه عن طريق زيارة موقعهم.
الخطوة 2. تسجيل الدخول إلى حسابك
إذا كان لديك حساب API Dog موجود، قم بتسجيل الدخول من خلال النقر على زر "تسجيل الدخول" في الزاوية العلوية اليمنى من الصفحة. إذا لم يكن لديك حساب، يمكنك إنشاء واحد من خلال النقر على زر "إنشاء حساب" واتباع التعليمات.
الخطوة 3. إنشاء مشروع جديد
بمجرد تسجيل الدخول، انقر على زر "إنشاء مشروع" لإنشاء مشروع جديد.
الخطوة 4. استيراد ملف OpenAPI
استورد ملف مواصفات OpenAPI في صفحة إنشاء المشروع. انقر على زر "استيراد" للمتابعة.
الخطوة 5. تحميل ملف OpenAPI الخاص بك:
في صفحة الاستيراد، سترى حقلًا حيث يمكنك إدخال عنوان URL لملف OpenAPI الخاص بك. إذا لم يكن لديك عنوان URL، يمكنك تحميل الملف من جهازك المحلي من خلال النقر على خيار "أو تحميل ملف" وتحديد الملف.
إدخال عنوان URL لملف JSON الخاص بي.
الخطوة 6. انتظر حتى يكتمل الاستيراد
اعتمادًا على حجم وتعقيد ملف OpenAPI الخاص بك، قد تستغرق عملية الاستيراد بضع دقائق.
ستقوم Apidog تلقائيًا بتحليل الملف وتوليد واجهة برمجة تطبيقات جديدة في حسابك.
الخطوة 7. تكوين إعدادات واجهة برمجة التطبيقات الخاصة بك
بعد استيراد ملف OpenAPI، سيتم توجيهك إلى صفحة الإعدادات لواجهة برمجة التطبيقات الجديدة الخاصة بك. يمكنك تكوين إعدادات مختلفة في هذه الصفحة، مثل اسم واجهة برمجة التطبيقات الخاصة بك، ووصفها، ومتطلبات المصادقة.
الخطوة 8. ابدأ في بناء واجهة برمجة التطبيقات الخاصة بك
بمجرد تكوين إعدادات واجهة برمجة التطبيقات الخاصة بك، يمكنك إضافة نقاط نهاية ووثائق إلى واجهة برمجة التطبيقات الخاصة بك باستخدام واجهة 'السلسة سهلة الاستخدام.
باتباع الخطوات البسيطة لاستيراد ملف مواصفات OpenAPI إلى Apidog، يمكنك إدارة وتوثيق مشاريع واجهة برمجة التطبيقات الخاصة بك بشكل أكثر كفاءة. عادةً ما يتضمن ملف المواصفات تفاصيل أساسية مثل نقطة النهاية POST، والمسار، والمعلمات، وأكواد الاستجابة.
بعد إضافة ملف المواصفات الخاص بك إلى Apidog، يمكنك الاستفادة من واجهته سهلة الاستخدام وأدواته القوية لضمان التناسق والموثوقية في عملية تطوير واجهات برمجة التطبيقات الخاصة بك. لذا، إذا كنت ترغب في توفير الوقت وتبسيط عملية تطوير واجهات برمجة التطبيقات الخاصة بك، فكر في استخدام مواصفات OpenAPI مع Apidog.
