توليد Swagger/OpenAPI لجافا: نظرة عامة على الأدوات |…

توليد Swagger/OpenAPI لجافا: نظرة عامة شاملة على الأدوات والمكتبات

\n\n

تطوير REST API الحديث في جافا لا يمكن تصوره بدون توثيق عالي الجودة. أصبح معيار OpenAPI (المعروف سابقًا باسم Swagger Specification) المعيار الصناعي الفعلي لوصف HTTP API. في هذه المقالة، سنقوم بتحليل المكتبات والأدوات الرئيسية لتوليد مواصفات OpenAPI في تطبيقات جافا، وإمكانياتها، وأمثلة الاستخدام، ومعايير الاختيار.

\n\n

ما هو OpenAPI ولماذا هو مطلوب؟

\n\n

OpenAPI هي مواصفة تصف RESTful API بتنسيق JSON أو YAML. تتضمن:

قائمة بنقاط النهاية وطرق HTTP؛
نماذج البيانات (مخططات الطلبات والاستجابات)؛
المعلمات (query، path، header)؛
معلومات حول المصادقة والتفويض.

التوثيق الذي يتم إنشاؤه بواسطة OpenAPI يسمح بإنشاء SDK للعميل تلقائيًا، وإجراء الاختبارات، والحفاظ على تحديث وصف API. بالنسبة لجافا، هناك العديد من الحلول الناضجة.

\n\n

1. SpringDoc OpenAPI (موصى به لـ Spring Boot)

\n\n

SpringDoc هي المكتبة الأكثر شيوعًا لتوليد OpenAPI 3 في نظام Spring البيئي. تقوم تلقائيًا بمسح المتحكمات (Controllers)، والتعليقات التوضيحية @RequestMapping، @GetMapping، وما إلى ذلك، وبناء المواصفة بناءً عليها.

\n\n

الإضافة (Maven)

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

\n\n

مثال على متحكم مع التعليقات التوضيحية

@RestController\n@RequestMapping("/api/users")\npublic class UserController {\n\n    @Operation(summary = "الحصول على مستخدم بواسطة المعرف")\n    @ApiResponses(value = {\n        @ApiResponse(responseCode = "200", description = "تم العثور على المستخدم"),\n        @ApiResponse(responseCode = "404", description = "لم يتم العثور على المستخدم")\n    })\n    @GetMapping("/{id}")\n    public ResponseEntity<User> getUser(@PathVariable Long id) {\n        // المنطق\n        return ResponseEntity.ok(new User(id, "إيفان", "ivan@example.com"));\n    }\n}

بعد تشغيل التطبيق، يكون التوثيق متاحًا على العنوان /swagger-ui.html، والمواصفة بتنسيق JSON على /v3/api-docs.

\n\n

2. Swagger Core (OpenAPI 3.0)

\n\n

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

\n\n

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

import io.swagger.v3.oas.models.*;\nimport io.swagger.v3.oas.models.info.*;\n\nOpenAPI openAPI = new OpenAPI()\n    .info(new Info()\n        .title("مثال API")\n        .version("1.0.0")\n        .description("توثيق تم إنشاؤه يدويًا"))\n    .path("/hello", new PathItem()\n        .get(new Operation()\n            .summary("تحية")\n            .operationId("sayHello")\n            .addParametersItem(new Parameter()\n                .name("name")\n                .in("query")\n                .required(false)\n                .schema(new StringSchema()))\n            .responses(new ApiResponses()\n                .addApiResponse("200", new ApiResponse()\n                    .description("موافق")\n                    .content(new Content()\n                        .addMediaType("text/plain", \n                            new MediaType().schema(new StringSchema())))))));\n\n// التسلسل إلى JSON\nObjectMapper mapper = new ObjectMapper();\nString json = mapper.writeValueAsString(openAPI);\nSystem.out.println(json);

\n\n