كيف تستخدم Swagger لتوثيق APIs في مشروعك

كيفية إضافة Swagger في مشروع Node.js

لا تضيع الوقت في كتابة الوثائق يدويًا! إضافة Swagger إلى Node.js بهذه الطريقة السحرية

في عالم تطوير البرمجيات، يعد التوثيق جزءًا أساسيًا من بناء واجهات برمجة التطبيقات (APIs) الناجحة. ومع ذلك، فإن كتابة التوثيق يدويًا قد يكون مرهقًا ويستهلك الكثير من الوقت. هنا يأتي دور Swagger ، أداة قوية تساعد المطورين على توثيق واجهات برمجة التطبيقات بشكل تلقائي وسريع. في هذا المقال، سنستعرض كيفية إضافة Swagger إلى مشروع Node.js.

ما هو Swagger؟

Swagger هو إطار عمل مفتوح المصدر يُستخدم لإنشاء وثائق APIs بطريقة سهلة ومتكاملة. يتيح Swagger للمبرمجين إنشاء واجهة رسومية تفاعلية تعرض جميع النقاط النهائية (endpoints) لواجهة برمجة التطبيقات، بالإضافة إلى طرق الاستدعاء المختلفة مثل GET وPOST وPUT وDELETE. كما يوفر Swagger أدوات لاختبار هذه النقاط مباشرة من خلال الواجهة.

لماذا يجب عليك استخدام Swagger في مشروع Node.js؟

• سهولة التوثيق : يقوم Swagger بتوليد الوثائق تلقائيًا بناءً على تعريفات API.
• تجربة تفاعلية : يمكن للمطورين اختبار النقاط النهائية دون الحاجة إلى أدوات خارجية.
• تحسين التعاون : يجعل Swagger من السهل على الفرق المختلفة (التطوير والاختبار والتسويق) فهم كيفية عمل API.

 تثبيت حزمة Swagger

لإضافة Swagger إلى مشروعك، تحتاج إلى تثبيت الحزم التالية:

npm i swagger-ui-express

npm i swagger-autogen

const swaggerAutogen = require('swagger-autogen')();

const doc = {
  info: {
    title: 'Node Shop API',
    description: 'API documentation for Node Shop',
  },
  servers: ['http://localhost:3000'],
};

const outputFile = './swagger.json';
const endpointsFiles = ['./main.js'];

swaggerAutogen(outputFile, endpointsFiles, doc);

node swagger.js;

const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));