جهّز ملف OpenAPI

جهّز وصفًا لواجهة HTTP API قبل استخدام مولّد Config في AGENTO. يوثق OpenAPI المسارات وHTTP methods والمدخلات والمصادقة والاستجابات. يجب أن يطابق الوصف الخادم المنشور لديك.

يستخدم AGENTO هذا الوصف، بينما يختار مشروعك طريقة إنشائه. يمكنك كتابته يدويًا، أو تصديره من أدوات API الموجودة، أو توليده من annotations وSchemas مشتركة.

اختر مصدر الوصف

أسماء Routes وحدها لا تصف الحقول المطلوبة أو قواعد التحقق أو المصادقة أو شكل الاستجابة. تحتاج أدوات التعليقات وSchemas إلى هذه المعلومات أيضًا. إذا استعنت بـ Model لصياغة الوصف، تحقق من ادعاءاته باستخدام handlers وmiddleware وSchemas واستجابات API الفعلية.

وثّق عملية في Express

تقرأ swagger-jsdoc تعليقات OpenAPI في ملفات الكود. ثبّتها ضمن development dependencies:

npm install --save-dev swagger-jsdoc

في ملف Route، ضع الوصف فوق handler الموجودة لديك. يفترض المثال أن المسار العام هو /api/services/:id:

/**
 * @openapi
 * /api/services/{id}:
 *   get:
 *     operationId: getService
 *     summary: Get a service
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *           minLength: 1
 *     responses:
 *       '200':
 *         description: Service details
 */
app.get("/api/services/:id", getService);

القيمتان app وgetService موجودتان في تطبيقك. يوثق هذا الجزء handler ولا ينشئ منطقها. تستخدم Express الصيغة :id في المسار، بينما يستخدم OpenAPI الصيغة {id}. ضمّن prefix العامة للـ Router في المسار الموثق؛ تصدير annotations لا يستنتج أين رُبط Router في التطبيق.

وثّق Route Handler في Next.js

في App Router يمكن أن توجد Endpoint داخل src/app/api/services/[id]/route.ts. أضف تعليق @openapi نفسه فوق GET الموجودة لديك، مع توثيق /api/services/{id}.

مثلًا، تقرأ handler التالية Parameter من Dynamic Route. أبقِ منطق جلب البيانات والاستجابة الخاص بتطبيقك:

export async function GET(
  _request: Request,
  context: { params: Promise<{ id: string }> },
) {
  const { id } = await context.params;
  const service = await getService(id);
  return Response.json(service);
}

هنا getService دالة موجودة في backend لديك. يحدد مسار الملف والدالة المصدّرة Route في Next.js، بينما يصف تعليق OpenAPI عقدها بصورة مستقلة. تستطيع أداة قراءة التعليقات فحص ملف .ts الأصلي دون تشغيل handler أو استيرادها.

عند استخدام Pages Router، وجّه أداة الفحص إلى ملفات pages/api أو src/pages/api، ووثق كل HTTP method مدعومة صراحة. يستهدف سكريبت التصدير التالي App Router؛ ولا يكيّف مسارات Pages Router أو تفرعات methods تلقائيًا.

صدّر التعليقات إلى ملف

احفظ export-openapi.mjs باسم scripts/export-openapi.mjs. شغّله من جذر المشروع. تفترض أنماط Express وجود ملفات Routes داخل src/routes؛ عدّلها لتطابق مشروعك. تغطي أنماط Next.js مجلد App Router سواء استخدمت src أم لا.

import swaggerJsdoc from "swagger-jsdoc";
import { writeFileSync } from "node:fs";

const target = process.argv[2];
const sources = {
  express: ["./src/routes/**/*.{js,ts}"],
  next: ["./src/app/api/**/route.{js,ts}", "./app/api/**/route.{js,ts}"],
};
if (!Object.hasOwn(sources, target)) {
  throw new Error("Usage: node scripts/export-openapi.mjs <express|next>");
}

const document = swaggerJsdoc({
  failOnErrors: true,
  definition: {
    openapi: "3.0.3",
    info: { title: "Application API", version: "1.0.0" },
    servers: [{ url: "https://api.example.com" }],
  },
  apis: sources[target],
});
if (!Object.keys(document.paths ?? {}).length) {
  throw new Error("No documented operations found. Check source paths and @openapi comments.");
}
writeFileSync("openapi.json", JSON.stringify(document, null, 2) + "\n");

لمشروع Express:

node scripts/export-openapi.mjs express

لمشروع Next.js App Router:

node scripts/export-openapi.mjs next

يعيد السكريبت بناء openapi.json من التعليقات عمدًا. استبدل https://api.example.com بعنوان خادمك الفعلي، أو مرّر --base-url عند توليد Config لاحقًا. طابق base path في الخادم مع prefix العامة في Routes لتجنب تكرارها.

افحص paths وInput Schemas وSecurity definitions الناتجة. يكشف failOnErrors مشاكل parsing والتحقق في التعليقات؛ ولا يثبت أن كل Route موثقة أو أن الوصف يطابق API المنشورة. وثق قيود Query وBody والمصادقة عند وجودها. لا تصف عملية محمية بأنها عامة لأن تعليقها أغفل المصادقة.

Swagger UI اختيارية. يمكنك حفظ openapi.json واستخدامه مع AGENTO دون نشر صفحة توثيق تفاعلية.

أعد استخدام Zod schemas

إذا كنت تتحقق من Input باستخدام Zod، يمكنك استخدام zod-to-openapi. تستطيع الأداة إعادة استخدام Schemas عند تعريف مسارات العمليات ومدخلات الطلب واستجاباته، ثم توليد مستند كامل عبر generateDocument.

لا تحدد Zod schemas وحدها HTTP Route التي تستخدمها. ما زلت تحتاج تعريف method وpath وoperation ID والمصادقة. استخدم إصدار مكتبة متوافقًا مع إصدار Zod لديك، وصدّر OpenAPI 3.0 أو 3.1 لتستخدم محوّل AGENTO.

قد يحتوي الوصف الناتج خصائص خارج نطاق التحويل. مثلًا، قد تنتج unions صيغة oneOf أو anyOf؛ ولا يدعم المحوّل defaults أو حقولًا غير محددة في المستوى الأول من body. راجع المدخلات المدعومة قبل التحويل. حافظ على صحة عقد API عند تعديل أدوات التوليد.

راجع الوصف ثم ولّد Config

تحقق من التالي قبل التحويل:

• تطابق المسارات العامة الكاملة وHTTP methods مع backend.
• وجود operationId فريد ومتوافق لكل عملية.
• توثيق الحقول المطلوبة والأنواع ومواضع Parameters والقيود.
• تطابق المصادقة مع Endpoint الفعلية، وغياب القيم السرية.
• توجيه عنوان الخادم وbase path إلى البيئة المقصودة.
• توافق العمليات مع نطاق الدعم.

ثم استخدم إصدارًا يحتوي المولّد:

npx --no-install agento-openapi openapi.json --output config.generated.yml

تابع إنشاء config.yml من OpenAPI لمراجعة النتيجة واستدعاء API والتعامل مع بيانات الاعتماد وتحديث Config بعد تغيير العقد. يوفر OpenAPI نقطة بداية للإعداد، بينما تحدد Config المراجعة سلوك Runtime في تطبيقك.

مراجع الأدوات

• swagger-jsdoc: التعليقات وخيارات التصدير
• Next.js: Route Handlers
• zod-to-openapi: Registries والمسارات وتوليد الوصف