Swagger/OpenAPI Kotlin जनरेशन: टूल्स और उदाहरण

Swagger/OpenAPI Kotlin जनरेशन: स्पेसिफिकेशन से तैयार कोड तक

आधुनिक API डेवलपमेंट में स्पष्ट डॉक्यूमेंटेशन और तेज़ कोड जनरेशन बहुत ज़रूरी है। Swagger/OpenAPI RESTful इंटरफेस को डिस्क्राइब करने का एक स्टैंडर्ड है, जो Kotlin में ऑटोमैटिक कोड जनरेट करता है। इससे DTO, कंट्रोलर और क्लाइंट लिखने की रूटीन वर्क से छुटकारा मिलता है। इस आर्टिकल में हम मुख्य टूल्स, सेटअप के उदाहरण और प्रैक्टिकल सीनारियो देखेंगे।

OpenAPI क्या है और Kotlin डेवलपर को इसकी ज़रूरत क्यों?

OpenAPI (पहले Swagger) YAML या JSON फॉर्मेट में एक स्पेसिफिकेशन है, जो एंडपॉइंट्स, डेटा मॉडल, रिक्वेस्ट और रिस्पॉन्स पैरामीटर्स को डिस्क्राइब करता है। Kotlin के लिए OpenAPI से कोड जनरेशन के फायदे:

• ऑटोमेशन — data क्लासेस, enum, कंट्रोलर इंटरफेस अपने आप बन जाते हैं
• कंसिस्टेंसी — कोड हमेशा डॉक्यूमेंटेशन से मेल खाता है
• समय की बचत — सीरियलाइज़ेशन/डीसीरियलाइज़ेशन मैन्युअली नहीं लिखना पड़ता
• फ्रेमवर्क सपोर्ट — Ktor, Spring Boot, Retrofit, Micronaut के साथ काम करता है

मुख्य जनरेशन टूल्स

Kotlin के लिए कई मैच्योर सॉल्यूशंस उपलब्ध हैं:

1. OpenAPI Generator (ऑफिशियल जनरेटर)

सबसे लोकप्रिय टूल। यह दर्जनों भाषाओं और फ्रेमवर्क को सपोर्ट करता है। Kotlin के लिए जनरेटर:

• kotlin-client — Ktor या Retrofit पर क्लाइंट
• kotlin-server — Ktor या Spring पर सर्वर
• kotlin-spring — Spring Boot कंट्रोलर

2. Ktor OpenAPI प्लगइन

Ktor फ्रेमवर्क के लिए प्लगइन, जो कोड से OpenAPI डॉक्यूमेंटेशन जनरेट करता है (रिवर्स अप्रोच)।

3. Swagger Codegen (लेगसी)

OpenAPI Generator का पुराना वर्जन, अभी भी इस्तेमाल होता है, लेकिन नए वर्जन पर माइग्रेट करने की सलाह दी जाती है।

उदाहरण: OpenAPI स्पेसिफिकेशन से Kotlin क्लाइंट जनरेशन

एक प्रैक्टिकल उदाहरण देखते हैं। मान लीजिए हमारे पास petstore.yaml फाइल है (स्टैंडर्ड Petstore स्पेसिफिकेशन)। OpenAPI Generator से Kotlin क्लाइंट जनरेट करेंगे।

स्टेप 1. OpenAPI Generator इंस्टॉल करें

Homebrew से (macOS/Linux):

brew install openapi-generator

या Docker से:

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

स्टेप 2. जनरेशन कॉन्फ़िगर करें

एक कॉन्फ़िगरेशन फाइल config.json बनाएं:

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

स्टेप 3. जनरेशन रन करें

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

नतीजा: जनरेटेड कोड

generated-client फोल्डर में ये फाइलें बनेंगी:

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

जनरेटेड DTO का उदाहरण:

@Serializable
data class Pet(
    val id: Long? = null,
    @SerialName("category")
    val category: Category? = null,
    @SerialName("name")
    val name: String,
    @SerialName("photoUrls")
    val photoUrls: List<String>,
    val tags: List<Tag>? = null,
    val status: PetStatus? = null
)

@Serializable
enum class PetStatus {
    @SerialName("available")
    Available,
    @SerialName("pending")
    Pending,
    @SerialName("sold")
    Sold
}

जनरेटेड API क्लाइंट (Ktor) का उदाहरण:

class PetApi(private val client: HttpClient) {

    suspend fun addPet(pet: Pet): Pet = client.post {
        url("http://petstore.swagger.io/v2/pet")
        contentType(ContentType.Applicatio