في السابق، ربما كنت تستخدم Swagger 2.0 (المعروف أيضًا باسم OAS 2)، لكن الآن حان الوقت للترقية إلى OpenAPI Specification (OAS) 3. في هذه المقالة، سوف نوضح النقاط الرئيسية لعملية الترقية والضروريات الخاصة بتوثيق واجهات برمجة التطبيقات باستخدام OAS 3.
بعض هذه النقاط قد لا تزال قابلة للتطبيق على مستندات OAS 2 السابقة (المعروفة سابقًا باسم Swagger)، لكن من الجدير بالذكر لأنني قد لا أكون قد أكدت عليها بالكامل من قبل.
أمثلة الشيفرة الموجودة في هذه المقالة مستخرجة من مواصفات OAS 3 لـ bookmarks.dev-api، المتاحة في ملف openapi.yaml على GitHub. يمكن عرض النتائج على bookmarks.dev/api/docs/.
إليك عشرة اعتبارات رئيسية:
1. اقرأ مستند المواصفة
اقرأ المقال "دليل حول ما هو جديد في OpenAPI 3.0"، الذي يشارك بعض التحديثات الرئيسية في أحدث إصدار من OAS ويقدم رؤى تفصيلية حول ما تحتاج إلى معرفته عند الانتقال من OAS 2.0 إلى OAS 3.0. هذه المقالة مبنية على الندوة عبر الإنترنت التي تستغرق ساعة واحدة "OpenAPI 3.0، وما يعنيه لمستقبل Swagger."
2. استخدم خدمة تحويل ويب
استخدم خدمة تحويل Swagger 2.0 إلى OpenAPI 3.0 لتحويل مواصفات Swagger الخاصة بك إلى OpenAPI 3.0.
إنه متاح عبر الإنترنت على https://converter.swagger.io/، ويمكنك أيضًا استخدامه كصورة Docker:
docker pull swaggerapi/swagger-converter:v1.0.2
docker run -it -p 8080:8080 --name swagger-converter swaggerapi/swagger-converter:v1.0.2
3. تحقق من المواصفة الخاصة بك ومعاينتها باستخدام محرر Swagger
مكن محرر Swagger من تعديل مواصفات واجهة برمجة التطبيقات بتنسيق YAML في متصفح الويب الخاص بك ومعاينة الوثائق على الفور.
يمكنك استخدامه عبر الإنترنت أو كإصدار تم نشره عبر npm أو صورة Docker. لمزيد من التفاصيل، راجع README الخاص بالمشروع.
4. عرض الوثائق الخاصة بك باستخدام واجهة Swagger
واجهة Swagger هي مجموعة من موارد HTML وJavaScript وCSS التي تُنتج توثيقًا جميلًا لواجهات برمجة التطبيقات المتوافقة مع Swagger بشكل ديناميكي.
يمكنك استخدامها مباشرة، مثلي، من خلال الوصول إلى توثيق واجهة Swagger عبر مسار واجهة برمجة التطبيقات، على سبيل المثال، bookmarks.dev/api/docs/. إليك مقتطف من الشيفرة من app.js:
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./docs/openapi/openapi.yaml');
app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
يمكن أن يكون تضمين ملف المواصفات المفتوح (openapi.yaml) في مراقبة nodemon الخاصة بك (مثل، nodemon --inspect ./bin/www --watch src --watch docs/openapi/openapi.yaml) مفيدًا، مما يتيح لك إعادة تحميل الواجهة دون الحاجة إلى إعادة تشغيل خادم ExpressJS يدويًا.
4.1. استخدم swagger-jsdoc لنهج البرمجة أولاً
نقطة أخرى تستحق الذكر هي أنه يمكنك استخدام swagger-jsdoc لتكامل Swagger من خلال تعليقات JSDoc في الشيفرة الخاصة بك. يفترض مشروع swagger-jsdoc أنك ترغب في توثيق الشيفرة الحالية والفعالة والعاملة بطريقة "تنفخ الحياة" فيها، مما ينتج عنه مواصفة يمكن إدخالها في أدوات Swagger الأخرى بدلاً من العكس.
حاليًا، أدير التوثيق في ملف openapi.yaml واحد، لكنني قد أفكر في استخدامه في المستقبل.
5. تجمع العمليات باستخدام العلامات
يمكنك تعيين قائمة علامات لكل عملية لواجهة برمجة التطبيقات، مما يجعل من السهل عرض العمليات حسب العلامات في واجهة Swagger ومحرر Swagger. للتحكم في الترتيب في واجهة Swagger، تحتاج إلى إضافتها كعلامات عالمية على المستوى الجذري. يمكنك أيضًا إضافة أوصاف وروابط لمستندات خارجية هناك.
إليك العلامات التي أستخدمها لواجهة برمجة التطبيقات:
yamlCopy code
tags:- name: rootdescription: تستخدم لتحديد نقاط النهاية الجذرية- name: versiondescription: وصول إلى إصدار المشروع و gitSha1- name: public-bookmarksdescription: وصول إلى العلامات العامة- name: personal-bookmarksdescription: عمليات على العلامات الشخصية- name: user-datadescription: عمليات على بيانات المستخدم- name: helperdescription: نقاط النهاية/العمليات المساعدة
6. تحديد عناوين URL الأساسية لواجهة برمجة التطبيقات مع الخوادم
في OpenAPI 3.0، تستخدم مصفوفة الخوادم لتحديد عنوان URL أساسي واحد أو أكثر لواجهة برمجة التطبيقات. تحل الخوادم محل الكلمات الرئيسية host و basePath و schemes المستخدمة في OpenAPI 2.0. كل خادم له عنوان URL ووصف اختياري بتنسيق Markdown.
yamlCopy code
servers:- url: http://localhost:3000/apidescription: خادم محلي للتطوير- url: https://www.bookmarks.dev/apidescription: الخادم الرئيسي (الإنتاج)
7. تعريف وإعادة استخدام الموارد مع المكونات
غالبًا، تشترك العديد من عمليات واجهة برمجة التطبيقات في معلمات مشتركة أو تعيد نفس بنية الاستجابة. لتجنب تكرار الشيفرة، يمكنك وضع التعريفات الشائعة في قسم المكونات العالمي والإشارة إليها باستخدام $ref.
على سبيل المثال، بالنسبة للاستجابة المشتركة لعدة عمليات حيث تظهر قائمة من العلامات، أعرّف ResponseListResponse تحت components > responses:
components:responses:BookmarkListResponse:description: قائمة العلاماتcontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Bookmark"
ثم، أشار إليها في عمليات مختلفة، مثل get-public-bookmarks:
yamlCopy code
/public/bookmarks:get:summary: إرجاع قائمة من العلامات العامة باستخدام معلمات الاستعلام.tags:- public-bookmarksparameters:- $ref: "#/components/parameters/searchTextQueryParam"- $ref: "#/components/parameters/limitQueryParam"- $ref: "#/components/parameters/locationQueryParam"responses:200:description: حسناً$ref: "#/components/responses/BookmarkListResponse"
لاحظ locationQueryParam المذكورة أعلاه. تم تعريفها تحت components > parameters وتم الإشارة إليها في عدة أماكن في مواصفة واجهة برمجة التطبيقات، بما في ذلك المثال الموضح أعلاه.
8. أضف أمثلة للوضوح
يمكنك إضافة أمثلة للمعلمات والخصائص والكائنات لجعل مواصفة خدمة الويب الخاصة بك أكثر وضوحًا. يمكن قراءة الأمثلة بواسطة الأدوات والمكتبات لواجهة برمجة التطبيقات الخاصة بك. على سبيل المثال، يمكن أن يستخدم أداة واجهة برمجة التطبيقات الوهمية قيم الأمثلة لإنشاء طلبات وهمية. يمكنك Specify أمثلة للكائنات والخصائص الفردية ومعلمات العمليات باستخدام المفاتيح example أو examples.
على سبيل المثال، يمكنك أن يكون لديك قيم معقدة كأمثلة لمعامل البحث النصي:
components:parameters:searchTextQueryParam:name: qin: querydescription: |
استعلام البحث (كلمات مفصولة بمسافات). الفلاتر الخاصة المتاحة:
* `lang:iso_language_code` - على سبيل المثال، `lang:en` للإنجليزية، `lang:es` للإسبانية، `lang:de` للألمانية
* `site:site_URL` - على سبيل المثال، إرجاع العلامات من [www.codepedia.org](htt
