توليد Swagger/OpenAPI لجافا: أفضل المكتبات

توليد Swagger/OpenAPI لجافا: دليل شامل للأدوات

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

ما هو Swagger و OpenAPI؟

Swagger هو مجموعة من الأدوات لتصميم وإنشاء وتوثيق واجهات برمجة التطبيقات REST. OpenAPI هي مواصفة تحدد معيارًا لوصف واجهات برمجة التطبيقات. Swagger هو التطبيق الأكثر شيوعًا لهذه المواصفة.

المكتبات الرئيسية لجافا

سنستعرض ثلاث أدوات رئيسية:

• SpringDoc OpenAPI — مكتبة حديثة لـ Spring Boot
• Swagger Core — المكتبة الأساسية من مبتكري Swagger
• OpenAPI Generator — أداة لتوليد الكود والتوثيق

1. SpringDoc OpenAPI

SpringDoc هو الخيار الأكثر شيوعًا لمشاريع Spring Boot. يتكامل تلقائيًا مع تطبيقك ويولد التوثيق بناءً على التعليقات التوضيحية وأنواع البيانات.

التثبيت والإعداد

أضف التبعية في ملف pom.xml:

<dependency>    <groupId>org.springdoc</groupId>    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>    <version>2.6.0</version></dependency>

مثال على الاستخدام

أنشئ وحدة تحكم بسيطة مع التوثيق:

@RestController@RequestMapping("/api/users")@Tag(name = "المستخدمون", description = "إدارة المستخدمين")public class UserController {

    @GetMapping("/{id}")    @Operation(summary = "الحصول على مستخدم بواسطة المعرف")    public ResponseEntity<User> getUser(            @Parameter(description = "معرف المستخدم")            @PathVariable Long id) {        // التنفيذ        return ResponseEntity.ok(new User(id, "إيفان"));    }

    @PostMapping    @Operation(summary = "إنشاء مستخدم جديد")    public ResponseEntity<User> createUser(            @RequestBody @Valid CreateUserRequest request) {        // التنفيذ        return ResponseEntity.status(201).body(new User(1L, request.getName()));    }}

بعد تشغيل التطبيق، سيكون التوثيق متاحًا على العنوان http://localhost:8080/swagger-ui.html.

2. Swagger Core

توفر مكتبة Swagger Core نهجًا منخفض المستوى لإنشاء مواصفة OpenAPI. وهي مناسبة للمشاريع التي تتطلب تحكمًا كاملاً في عملية التوليد.

مثال على إنشاء المواصفة يدويًا

import io.swagger.v3.oas.models.*;import io.swagger.v3.oas.models.info.*;

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("Pet Store API")        .description("API لإدارة الحيوانات الأليفة")        .version("1.0.0")        .contact(new Contact()            .name("المطور")            .email("dev@example.com")))    .addServersItem(new Server()        .url("https://api.example.com/v1")        .description("خادم الإنتاج"));

// إضافة المسارات والمكوناتPaths paths = new Paths();paths.addPathItem("/pets", new PathItem()    .get(new Operation()        .operationId("listPets")        .summary("الحصول على قائمة الحيوانات الأليفة")));openAPI.setPaths(paths);

3. OpenAPI Generator

OpenAPI Generator هو أداة يمكنها توليد كل من التوثيق وكود العميل/الخادم بناءً على مواصفة OpenAPI.

الاستخدام في Maven

أضف الإضافة في ملف pom.