كيف تنشئ توثيق واجهة برمجية باستخدام Swagger؟

Question

Accepted Answer

يدمج NestJS مع **Swagger/OpenAPI** عبر `@nestjs/swagger` لـ **إنشاء توثيق واجهة برمجية تفاعلي بشكل تلقائي** من الكود — المتحكمات والمسارات والـ DTOs والمزخرفات. وينتج عن ذلك واجهة مستخدم قابلة للاستعراض حيث يمكن للمطورين استكشاف واختبار نقاط النهاية، مع الحفاظ على التزامن مع الكود.

## إعداد Swagger

```ts
// main.ts
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

const config = new DocumentBuilder()
  .setTitle("Users API")
  .setDescription("The users API documentation")
  .setVersion("1.0")
  .addBearerAuth()                       // document JWT auth
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api/docs", app, document);   // serve the UI at /api/docs
```

مع بضعة أسطر، يقوم Swagger بفحص تطبيقك وتقديم مستندات تفاعلية في `/api/docs` — مع عكس المسارات والمعاملات والـ DTOs تلقائياً.

## توثيق DTOs والاستجابات

```ts
export class CreateUserDto {
  @ApiProperty({ example: "ann@example.com", description: "User email" })
  email: string;

@ApiProperty({ minLength: 8 })
  password: string;

@ApiPropertyOptional()                 // optional field in the docs
  age?: number;
}
```

مزخرفات `@ApiProperty` تضيف أوصافاً وأمثلة وقيوداً إلى حقول DTO، مما يثري المخطط الناتج. (الكثير منها يُستنتج تلقائياً من أنواع TypeScript ومزخرفات `class-validator` — يمكن للـ `CLI plugin` أن يقلل حتى هذا الكود الإضافي.)

## توثيق نقاط النهاية

```ts
@ApiTags("users")                        // group endpoints in the UI
@Controller("users")
export class UsersController {
  @Post()
  @ApiOperation({ summary: "Create a user" })
  @ApiResponse({ status: 201, description: "User created", type: User })
  @ApiResponse({ status: 400, description: "Invalid input" })
  create(@Body() dto: CreateUserDto) {}
}
```

مزخرفات مثل `@ApiTags` و `@ApiOperation` و `@ApiResponse` تضيف أوصافاً وتجمع نقاط النهاية وتوثق الاستجابات الممكنة.

## ما تحصل عليه

```text
✓ Interactive UI (Swagger UI) — browse, read, and TEST endpoints in the browser
✓ Auto-generated, always in sync with the code (no separate doc to maintain)
✓ The OpenAPI spec (JSON) — usable to generate client SDKs, for contract testing, etc.
✓ Request/response schemas, validation rules, auth requirements all documented
```

## لماذا يهم هذا

توثيق واجهة البرمجية ضروري لأي واجهة برمجية يستهلكها آخرون — فريق الواجهة الأمامية أو التطبيقات المحمولة أو المتكاملون من جهات خارجية أو حتى نفسك في المستقبل — وتكامل Swagger في NestJS يجعل إنتاج مستندات عالية الجودة سهلاً وموثوقاً بشكل ملحوظ.

الميزة الرئيسية هي أن التوثيق يُنشأ **بشكل تلقائي من الكود** (المتحكمات والمسارات والـ DTOs والمزخرفات)، لذا فهو يبقى **متزامناً** مع التنفيذ الفعلي بدلاً من التأخر مثل المستندات المكتوبة يدوياً التي لا مفر منها.

فهمه ذو قيمة لأن المستندات الجيدة للواجهة البرمجية تحسن بشكل كبير من تجربة المطور وتقلل احتكاك التكامل: **Swagger UI** التفاعلي يسمح للمستهلكين باستكشاف واختبار نقاط النهاية مباشرة في المتصفح، والمواصفات **OpenAPI** المُنشأة يمكن أن تدفع إنشاء SDK للعميل واختبار العقود.

معرفة كيفية إعداد Swagger وإثراء المستندات بالمزخرفات (`@ApiProperty` و `@ApiTags` و `@ApiOperation` و `@ApiResponse`) وتوثيق المصادقة هي معرفة عملية مطلوبة بشكل متكرر — الواجهات البرمجية الموثقة جيداً هي معيار احترافي وعلامة من علامات جودة عمل الخادم الخلفي.

لأن NestJS يستفيد من بنية المزخرفات/DTO الخاصة به لإنشاء الكثير بشكل تلقائي (مع الحد الأدنى من الجهد الإضافي)، لا يوجد عذر تقريباً لعدم وجود مستندات ممتازة، مما يجعل هذه قدرة مهمة وعالية القيمة في مشاريع NestJS الحقيقية.