OpenAPI / Swagger Java: طرق، أمثلة، تثبيت

ما هو OpenAPI / Swagger ولماذا يحتاجه مطور جافا؟

OpenAPI (المعروف سابقًا باسم Swagger) هو مواصفة قياسية لوصف وإنشاء وتوثيق واستهلاك RESTful API. بالنسبة لمطور جافا، تُعد مكتبات OpenAPI / Swagger أداة لا غنى عنها تعمل على أتمتة عملية توثيق API وإنشاء كود العميل.

الأسباب الرئيسية لاستخدام OpenAPI / Swagger في مشاريع جافا:

توليد تلقائي للتوثيق — تقوم المكتبة بتحليل كودك (تعليقات Spring Boot، JAX-RS) وإنشاء توثيق تفاعلي بتنسيق Swagger UI.
التوحيد القياسي — تنسيق موحد لوصف API، مفهوم لكل من البشر والآلات.
توليد كود العميل — يمكنك إنشاء عميل جافا لأي API موصوف في OpenAPI.
الاختبار — يتيح لك Swagger UI إرسال طلبات إلى API مباشرة من المتصفح.
التكامل مع CI/CD — يمكنك التحقق من توافق API مع المواصفات أثناء مرحلة البناء.

في هذه المقالة، سنستعرض مكتبتي جافا الرئيسيتين: springdoc-openapi (لـ Spring Boot) و Swagger Core (لـ JAX-RX والأطر الأخرى).

تثبيت مكتبة OpenAPI / Swagger لجافا

يعتمد التثبيت على الإطار المستخدم. دعنا نستعرض الخيارين الرئيسيين.

الخيار 1: Spring Boot (springdoc-openapi)

أضف التبعية إلى ملف pom.xml (Maven):

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

لـ Gradle (build.gradle):

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

الخيار 2: JAX-RS / Jakarta (Swagger Core)

Maven:

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2-jakarta</artifactId>
    <version>2.2.22</version>
</dependency>

Gradle:

implementation 'io.swagger.core.v3:swagger-jaxrs2-jakarta:2.2.22'

بداية سريعة: أول مثال مع Spring Boot

بعد إضافة تبعية springdoc-openapi إلى مشروع Spring Boot، يصبح Swagger UI متاحًا تلقائيًا على الرابط http://localhost:8080/swagger-ui.html. لننشئ وحدة تحكم بسيطة:

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

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

    @GetMapping("/{id}")
    @Operation(summary = "الحصول على مستخدم بواسطة المعرف")
    public String getUser(@PathVariable Long id) {
        return "مستخدم بالمعرف: " + id;
    }

    @PostMapping
    @Operation(summary = "إنشاء مستخدم جديد")
    public String createUser(@RequestBody String userName) {
        return "تم إنشاء المستخدم: " + userName;
    }
}

بعد تشغيل التطبيق، افتح http://localhost:8080/swagger-ui.html — ستظهر لك وثائق تفاعلية مع إمكانية إرسال الطلبات.