توليد Swagger/OpenAPI على Kotlin: أدوات وأمثلة

توليد Swagger/OpenAPI لـ Kotlin: من المواصفات إلى الكود الجاهز

\n\n

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

\n\n

ما هو OpenAPI ولماذا يحتاجه مطور Kotlin؟

\n\n

OpenAPI (المعروف سابقًا باسم Swagger) هو مواصفات بتنسيق YAML أو JSON تصف نقاط النهاية، نماذج البيانات، معاملات الطلبات والاستجابات. بالنسبة لـ Kotlin، يوفر توليد الكود من OpenAPI ما يلي:

\n

\n
• الأتمتة — إنشاء فئات data، enum، واجهات وحدات التحكم
\n
• التوافق — الكود يتوافق دائمًا مع التوثيق
\n
• توفير الوقت — لا حاجة لكتابة التسلسل/إلغاء التسلسل يدويًا
\n
• دعم الأطر — Ktor, Spring Boot, Retrofit, Micronaut
\n

\n\n

الأدوات الرئيسية للتوليد

\n\n

توجد عدة حلول ناضجة لـ Kotlin:

\n\n

1. OpenAPI Generator (المولد الرسمي)

\n

الأداة الأكثر شيوعًا. تدعم عشرات اللغات والأطر. لـ Kotlin، تتوفر المولدات التالية:

\n

\n
• kotlin-client — عميل على Ktor أو Retrofit
\n
• kotlin-server — خادم على Ktor أو Spring
\n
• kotlin-spring — وحدات تحكم Spring Boot
\n

\n\n

2. إضافة Ktor OpenAPI

\n

إضافة لإطار Ktor، تقوم بتوليد توثيق OpenAPI من الكود (نهج عكسي).

\n\n

3. Swagger Codegen (قديم)

\n

سلف OpenAPI Generator، لا يزال مستخدمًا، لكن يُوصى بالترحيل إلى الإصدار الجديد.

\n\n

مثال: توليد عميل Kotlin من مواصفات OpenAPI

\n\n

لننظر إلى مثال عملي. لنفترض أن لدينا ملف petstore.yaml (مواصفات Petstore القياسية). سنقوم بتوليد عميل Kotlin باستخدام OpenAPI Generator.

\n\n

الخطوة 1. تثبيت OpenAPI Generator

\n

عبر Homebrew (macOS/Linux):

\n

brew install openapi-generator

\n

أو عبر Docker:

\n

docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate \\\n  -i /local/petstore.yaml \\\n  -g kotlin-client \\\n  -o /local/out/kotlin-client

\n\n

الخطوة 2. إعداد التوليد

\n

لنقم بإنشاء ملف الإعداد config.json:

\n

{\n  "packageName": "com.pythonlib.petstore.client",\n  "library": "ktor",\n  "serializationLibrary": "kotlinx_serialization",\n  "useCoroutines": true\n}

\n\n

الخطوة 3. تشغيل التوليد

\n

openapi-generator generate \\\n  -i petstore.yaml \\\n  -g kotlin-client \\\n  -o ./generated-client \\\n  -c config.json

\n\n

النتيجة: الكود المولد

\n

في المجلد generated-client ستظهر:

\n

\n
• src/main/kotlin/com/pythonlib/petstore/client/models/Pet.kt
\n
• src/main/kotlin/com/pythonlib/petstore/client/api/PetApi.kt
\n

\n\n

مثال على DTO المولد:

\n

@Serializable\ndata class Pet(\n    val id: Long? = null,\n    @SerialName("category")\n    val category: Category? = null,\n    @SerialName("name")\n    val name: String,\n    @SerialName("photoUrls")\n    val photoUrls: List<String>,\n    val tags: List<Tag>? = null,\n    val status: PetStatus? = null\n)\n\n@Serializable\nenum class PetStatus {\n    @SerialName("available")\n    Available,\n    @SerialName("pending")\n    Pending,\n    @SerialName("sold")\n    Sold\n}

\n\n

مثال على عميل API المولد (Ktor):

\n

class PetApi(private val client: HttpClient) {\n\n    suspend fun addPet(pet: Pet): Pet = cli