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

توليد Swagger/OpenAPI لـ Kotlin: دليل كامل

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

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

OpenAPI هو معيار لوصف REST API بتنسيق YAML أو JSON. يتيح لك:

• توليد كود العميل تلقائيًا لتطبيقات Android
• إنشاء نماذج خادم أولية ووحدات تحكم
• الحفاظ على تحديث التوثيق
• تسريع التطوير في الفرق التي يعمل فيها الواجهة الخلفية والواجهة الأمامية بالتوازي

بالنسبة لـ Kotlin، الذي يُستخدم بنشاط في تطوير الخوادم (Ktor, Spring Boot) وتطبيقات الهواتف المحمولة (Android)، يصبح توليد الكود من OpenAPI أداة لا غنى عنها.

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

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

الأداة الأكثر شيوعًا هي OpenAPI Generator. وهي تدعم العديد من اللغات والأطر، بما في ذلك Kotlin.

التثبيت عبر Gradle:

plugins {    id("org.openapi.generator") version "7.2.0"}

openApiGenerate {    generatorName.set("kotlin")    inputSpec.set("$rootDir/src/main/resources/openapi.yaml")    outputDir.set("$buildDir/generated")    packageName.set("com.example.api")    configOptions.set(mapOf(        "dateLibrary" to "kotlinx-datetime",        "useCoroutines" to "true"    ))}

2. توليد عميل لـ Spring Boot

إذا كان خادمك مكتوبًا بـ Spring Boot، يمكنك توليد عميل Kotlin:

openApiGenerate {    generatorName.set("kotlin-spring")    inputSpec.set("${projectDir}/api-spec.yaml")    outputDir.set("${buildDir}/generated")    apiPackage.set("com.example.api")    modelPackage.set("com.example.model")    configOptions.set(mapOf(        "library" to "spring-boot",        "useTags" to "true"    ))}

3. توليد لـ Ktor

Ktor هو إطار عمل غير متزامن حديث لـ Kotlin. يدعمه OpenAPI Generator أيضًا:

openApiGenerate {    generatorName.set("kotlin-ktor")    inputSpec.set("api.yaml")    outputDir.set("generated")    configOptions.set(mapOf(        "dateLibrary" to "kotlinx-datetime",        "serializationLibrary" to "kotlinx_serialization"    ))}

مثال عملي: من المواصفات إلى الكود

لنأخذ مثالًا بسيطًا. لنفترض أن لدينا مواصفات pets.yaml:

openapi: "3.0.0"info:  title: Pet Store API  version: "1.0"paths:  /pets:    get:      operationId: listPets      responses:        '200':          description: OK          content:            application/json:              schema:                type: array                items:                  $ref: '#/components/schemas/Pet'components:  schemas:    Pet:      type: object      properties:        id:          type: integer        name:          type: string

بعد التوليد، سنحصل على:

// Pet.kt (data class مولدة)data class Pet(    val id: Int,    val name: String)

// PetsApi.kt (واجهة مولدة)interface PetsApi {    suspend fun listPets(): List<Pet>}

إعدادات متقدمة وتخصيص

استخدام قوالب Mustache المخصصة

يستخدم OpenAPI Generator قوالب Mustache. يمكنك تجاوزها:

openApiGenerate {    templateDir.set("$rootDir/templates/kotlin")    // أضف