Swagger/OpenAPI जनरेशन Java के लिए: टूल्स की समीक्षा |…

Swagger/OpenAPI जनरेशन Java के लिए: टूल्स और लाइब्रेरीज़ की पूरी गाइड

Java में REST API डेवलपमेंट में अच्छी डॉक्यूमेंटेशन का होना बहुत ज़रूरी है। OpenAPI स्टैंडर्ड (जिसे पहले Swagger Specification कहा जाता था) HTTP API को डिस्क्राइब करने का इंडस्ट्री स्टैंडर्ड बन गया है। इस आर्टिकल में हम Java एप्लिकेशन में OpenAPI स्पेसिफिकेशन जनरेट करने वाली मुख्य लाइब्रेरीज़, उनकी क्षमताएँ, उपयोग के उदाहरण और चुनने के मापदंडों पर विस्तार से चर्चा करेंगे।

OpenAPI क्या है और इसकी ज़रूरत क्यों है?

OpenAPI एक स्पेसिफिकेशन है जो RESTful API को JSON या YAML फॉर्मेट में डिस्क्राइब करता है। इसमें शामिल हैं:

एंडपॉइंट्स और HTTP मेथड्स की लिस्ट;
डेटा मॉडल (रिक्वेस्ट और रिस्पॉन्स स्कीमा);
पैरामीटर्स (query, path, header);
ऑथेंटिकेशन और ऑथराइज़ेशन की जानकारी।

OpenAPI से जनरेट की गई डॉक्यूमेंटेशन की मदद से आप ऑटोमैटिकली क्लाइंट SDK बना सकते हैं, टेस्टिंग कर सकते हैं और API का विवरण अपडेट रख सकते हैं। Java के लिए कई परिपक्व समाधान मौजूद हैं।

1. SpringDoc OpenAPI (Spring Boot के लिए सुझाव)

SpringDoc Spring इकोसिस्टम में OpenAPI 3 जनरेट करने की सबसे लोकप्रिय लाइब्रेरी है। यह ऑटोमैटिकली कंट्रोलर, @RequestMapping, @GetMapping जैसे एनोटेशन को स्कैन करती है और उनके आधार पर स्पेसिफिकेशन बनाती है।

Maven में जोड़ना

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

एनोटेशन के साथ कंट्रोलर का उदाहरण

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "यूज़र को ID से प्राप्त करें")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "यूज़र मिल गया"),
        @ApiResponse(responseCode = "404", description = "यूज़र नहीं मिला")
    })
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id) {
        // लॉजिक
        return ResponseEntity.ok(new User(id, "राहुल", "rahul@example.com"));
    }
}

एप्लिकेशन चलाने के बाद, डॉक्यूमेंटेशन /swagger-ui.html पर और JSON स्पेसिफिकेशन /v3/api-docs पर उपलब्ध होगी।

2. Swagger Core (OpenAPI 3.0)

Swagger Core स्पेसिफिकेशन बनाने वालों की एक लो-लेवल लाइब्रेरी है। यह प्रोग्रामेटिक रूप से OpenAPI ऑब्जेक्ट बनाने और उन्हें JSON/YAML में सीरियलाइज़ करने की सुविधा देती है। यह तब उपयोगी है जब आपको जनरेशन पर बारीक नियंत्रण चाहिए।

प्रोग्रामेटिक रूप से स्पेसिफिकेशन बनाने का उदाहरण

import io.swagger.v3.oas.models.*;
import io.swagger.v3.oas.models.info.*;

OpenAPI openAPI = new OpenAPI()
    .info(new Info()
        .title("उदाहरण API")
        .version("1.0.0")
        .description("मैन्युअली बनाई गई डॉक्यूमेंटेशन"))
    .path("/hello", new PathItem()
        .get(new Operation()
            .summary("अभिवादन")
            .operationId("sayHello")
            .addParametersItem(new Parameter()
                .name("name")
                .in("query")
                .required(false)
                .schema(new StringSchema()))
            .responses(new ApiResponses()
                .addApiResponse("200", new ApiResponse()
                    .description("ठीक है")
                    .content(new Content()
                        .addMediaType("text/plain", 
                            new MediaType().schema(new StringSchema())))))));

// JSON में सीरियलाइज़ करना
ObjectMapper mapper = new ObjectMapper();
String json = mapper.writeValueAsString(openAPI);
System.out.println(json);