موضوع

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

فيما يلي دليل تفصيلي لإعداد Swagger في تطبيق Next.js:

الخطوة 1: تثبيت الحزم الضرورية

أولا ، قم بتثبيت الحزم المطلوبة: swagger-jsdoc و swagger-ui-express.

npm install swagger-jsdoc swagger-ui-express

الخطوة 2: تكوين التباهي

قم بإنشاء ملف تكوين Swagger ، swagger.js ، في جذر مشروعك أو دليل مناسب:

// swagger.js
const swaggerJSDoc = require('swagger-jsdoc');

const swaggerDefinition = {
  openapi: '3. 0. 0',
  info: {
    title: 'Next.js Swagger API',
    version: '1. 0. 0',
    description: 'API documentation using Swagger for a Next.js application',
  },
  servers: [
    {
      url: 'http://localhost:3000/api',
    },
  ],
};

const options = {
  swaggerDefinition,
  apis: ['./pages/api/*. js'], // Path to the API docs
};

const swaggerSpec = swaggerJSDoc(options);

module.exports = swaggerSpec;

الخطوة 3: إنشاء مسار واجهة مستخدم Swagger

بعد ذلك ، قم بإنشاء مسار API جديد في Next.js لخدمة واجهة مستخدم Swagger.

مثال: إنشاء ملف جديد pages/api/docs.js:

// pages/api/docs.js
import { withApiAuthRequired } from '@auth0/nextjs-auth0';
import swaggerUi from 'swagger-ui-express';
import swaggerSpec from '../../swagger';

const handler = async (req, res) => {
  swaggerUi.setup(swaggerSpec)(req, res);
};

export default withApiAuthRequired(handler);

// middleware to handle swagger
export const config = {
  api: {
    bodyParser: false,
  },
};

الخطوة 4: إضافة تعليقات وثائق واجهة برمجة التطبيقات

أضف تعليقات JSDoc إلى نقاط نهاية واجهة برمجة التطبيقات في pages/api/.

مثال: pages/api/example.js:

/**
 * @swagger
 * /example:
 *   get:
 *     description: This is an example endpoint
 *     responses:
 *       200:
 *         description: Returns a success message.
 */

export default function handler(req, res) {
  res.status(200). json({ message: 'Success' });
}

الخطوة 5: وثائق الوصول

قم بتشغيل تطبيق Next.js الخاص بك وانتقل إلى http://localhost:3000/api/docs للوصول إلى واجهة مستخدم Swagger وعرض وثائق واجهة برمجة التطبيقات الخاصة بك.

مثال على بنية الملف

إليك بنية ملف مبسطة لمشروعك Next.js باستخدام Swagger:

.
├── pages
│   ├── api
│   │   ├── docs.js
│   │   └── example.js
├── swagger.js
└── package.json

خاتمة

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

يتضمن دمج Swagger مع تطبيق Next.js باستخدام جهاز توجيه التطبيق بضع خطوات إضافية. إليك كيف يمكنك تحقيق ذلك:

الخطوة 1: تثبيت الحزم الضرورية

أولا ، ستحتاج إلى تثبيت الحزم المطلوبة: swagger-jsdoc و swagger-ui-express.

npm install swagger-jsdoc swagger-ui-express

الخطوة 2: تكوين التباهي

قم بإنشاء ملف تكوين Swagger ، swagger.js ، في جذر مشروعك أو دليل مناسب:

// swagger.js
const swaggerJSDoc = require('swagger-jsdoc');

const swaggerDefinition = {
  openapi: '3. 0. 0',
  info: {
    title: 'Next.js Swagger API',
    version: '1. 0. 0',
    description: 'API documentation using Swagger for a Next.js application',
  },
  servers: [
    {
      url: 'http://localhost:3000/api',
    },
  ],
};

const options = {
  swaggerDefinition,
  apis: ['./app/api/**/*. js'], // Path to the API docs
};

const swaggerSpec = swaggerJSDoc(options);

module.exports = swaggerSpec;

الخطوة 3: إنشاء مسار واجهة مستخدم Swagger

بعد ذلك ، قم بإنشاء مسار API جديد في Next.js لخدمة واجهة مستخدم Swagger.

مثال: إنشاء ملف جديد app/api/docs/route.js:

// app/api/docs/route.js
import { NextResponse } from 'next/server';
import swaggerUi from 'swagger-ui-express';
import swaggerSpec from '../../../swagger';

export async function GET(req, res) {
  return await swaggerUi.setup(swaggerSpec, {
    swaggerOptions: {
      url: req.url,
    },
  })(req, res);
}

export const config = {
  api: {
    bodyParser: false,
  },
};

الخطوة 4: إضافة تعليقات وثائق واجهة برمجة التطبيقات

أضف تعليقات JSDoc إلى نقاط نهاية واجهة برمجة التطبيقات. تأكد من إضافة تعليقات توضيحية إلى جميع نقاط نهاية واجهة برمجة التطبيقات بشكل صحيح باستخدام تعليقات JSDoc.

مثال: app/api/example/route.js:

/**
 * @swagger
 * /example:
 *   get:
 *     description: This is an example endpoint
 *     responses:
 *       200:
 *         description: Returns a success message.
 */

export async function GET(req, res) {
  res.status(200). json({ message: 'Success' });
  return NextResponse.json({ message: 'Success' });
}

الخطوة 5: وثائق الوصول

قم بتشغيل تطبيق Next.js الخاص بك وانتقل إلى http://localhost:3000/api/docs للوصول إلى واجهة مستخدم Swagger وعرض وثائق واجهة برمجة التطبيقات الخاصة بك.

مثال على بنية الملف

إليك بنية ملف مبسطة لمشروعك Next.js مع تكامل Swagger:

.
├── app
│   ├── api
│   │   ├── docs
│   │   │   └── route.js
│   │   └── example
│   │       └── route.js
├── swagger.js
└── package.json

خاتمة

من خلال هذه الخطوات ، نجحت في دمج Swagger في تطبيق Next.js الخاص بك باستخدام جهاز توجيه التطبيق. يوفر هذا الإعداد واجهة واضحة وتفاعلية لوثائق واجهة برمجة التطبيقات، مما يسهل على المطورين فهم واجهات برمجة التطبيقات واستخدامها.