OpenAPI / Swagger Java: तरीके, उदाहरण, इंस्टॉलेशन |…

OpenAPI / Swagger क्या है और Java डेवलपर को इसकी आवश्यकता क्यों है?

OpenAPI (पहले Swagger के नाम से जाना जाता था) RESTful API को डिस्क्राइब, क्रिएट, डॉक्यूमेंट और कंज़्यूम करने के लिए एक स्पेसिफिकेशन है। Java डेवलपर के लिए, OpenAPI / Swagger लाइब्रेरीज़ एक अनिवार्य टूल हैं जो API डॉक्यूमेंटेशन और क्लाइंट कोड जनरेशन की प्रक्रिया को ऑटोमेट करती हैं।

Java प्रोजेक्ट्स में OpenAPI / Swagger का उपयोग करने के मुख्य कारण:

ऑटोमैटिक डॉक्यूमेंटेशन जनरेशन — लाइब्रेरी आपके कोड (Spring Boot एनोटेशन, JAX-RS) का विश्लेषण करती है और Swagger UI फॉर्मेट में इंटरैक्टिव डॉक्यूमेंटेशन बनाती है।
स्टैंडर्डाइज़ेशन — API डिस्क्रिप्शन का एक समान फॉर्मेट, जो इंसानों और मशीनों दोनों के लिए समझने योग्य है।
क्लाइंट कोड जनरेशन — OpenAPI में डिस्क्राइब किए गए किसी भी API के लिए Java क्लाइंट जनरेट किया जा सकता है।
टेस्टिंग — Swagger UI आपको ब्राउज़र से सीधे API पर रिक्वेस्ट भेजने की सुविधा देता है।
CI/CD इंटीग्रेशन — बिल्ड स्टेज पर API स्पेसिफिकेशन की जांच की जा सकती है।

इस आर्टिकल में हम दो मुख्य Java लाइब्रेरीज़ पर ध्यान देंगे: springdoc-openapi (Spring Boot के लिए) और Swagger Core (JAX-RS और अन्य फ्रेमवर्क के लिए)।

Java के लिए 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 के साथ पहला उदाहरण

Spring Boot प्रोजेक्ट में springdoc-openapi डिपेंडेंसी जोड़ने के बाद, 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 = "ID द्वारा उपयोगकर्ता प्राप्त करें")
    public String getUser(@PathVariable Long id) {
        return "User with ID: " + id;
    }

    @PostMapping
    @Operation(summary = "नया उपयोगकर्ता बनाएं")
    public String createUser(@RequestBody String userName) {
        return "Created user: " + userName;
    }
}

एप्लिकेशन चलाने के बाद, http://localhost:8080/swagger-ui.html खोलें — आपको इंटरैक्टिव डॉक्यूमेंटेशन दिखाई देगा जिसमें रिक्वेस्ट भेजने की सुविधा भी होगी।