Swagger-PHP के लिए PHP: पूर्ण गाइड उदाहरणों के साथ

1. यह क्या है और इसकी आवश्यकता क्यों है

Swagger-PHP, PHP भाषा के लिए एक शक्तिशाली लाइब्रेरी है जो आपके कोड में एनोटेशन के आधार पर आपके REST API के लिए OpenAPI (पहले Swagger) स्पेसिफिकेशन को स्वचालित रूप से जनरेट करती है। सभी एंडपॉइंट्स, पैरामीटर्स, डेटा मॉडल और रिस्पॉन्स का वर्णन करने वाली बड़ी YAML या JSON फ़ाइलें मैन्युअल रूप से लिखने के बजाय, आप अपने PHP एप्लिकेशन के कंट्रोलर, मॉडल और रूट में सीधे विशेष कमेंट (एनोटेशन) जोड़ते हैं। लाइब्रेरी इन एनोटेशन का विश्लेषण करती है और एक पूर्ण, मान्य OpenAPI स्पेसिफिकेशन बनाती है जिसे JSON या YAML फॉर्मेट में एक्सपोर्ट किया जा सकता है।

इसकी आवश्यकता क्यों है? आधुनिक वेब डेवलपमेंट में, API फ्रंटएंड, मोबाइल ऐप्स और तीसरे पक्ष की सेवाओं के बीच इंटरैक्शन का मुख्य इंटरफ़ेस है। डॉक्यूमेंटेशन को अप-टू-डेट रखना एक सिरदर्द हो सकता है। Swagger-PHP इस समस्या को हल करता है, डॉक्यूमेंटेशन को सीधे सोर्स कोड से जोड़कर। यदि आप किसी एंडपॉइंट के लॉजिक को बदलते हैं, तो आप उसके बगल में एनोटेशन भी बदलते हैं। डॉक्यूमेंटेशन हमेशा API के वास्तविक व्यवहार से मेल खाता है। इससे काम के घंटे बचते हैं, इंटीग्रेशन त्रुटियां कम होती हैं, और आपका प्रोजेक्ट नए डेवलपर्स के लिए पारदर्शी बनता है।

इसके अलावा, जनरेट की गई OpenAPI स्पेसिफिकेशन का उपयोग दर्जनों टूल्स के साथ किया जा सकता है: Swagger UI (इंटरैक्टिव डॉक्यूमेंटेशन जहां आप ब्राउज़र से सीधे रिक्वेस्ट टेस्ट कर सकते हैं), JavaScript, Python, Java और अन्य भाषाओं के लिए क्लाइंट SDK जनरेटर, टेस्टिंग और वैलिडेशन टूल्स (जैसे Postman या Insomnia), और मॉक सर्वर के ऑटोमैटिक जनरेशन के लिए। Swagger-PHP PHP API को डॉक्यूमेंट करने का डी-फैक्टो मानक है।

2. इंस्टॉलेशन

इंस्टॉलेशन Composer के माध्यम से किया जाता है - PHP के लिए मानक पैकेज मैनेजर। अपने प्रोजेक्ट की रूट डायरेक्टरी में निम्न कमांड चलाएँ:

composer require zircote/swagger-php

इंस्टॉलेशन के बाद, आपके प्रोजेक्ट में vendor/zircote/swagger-php डायरेक्टरी बन जाएगी। लाइब्रेरी को PHP 8.0 या उससे ऊपर के वर्जन की आवश्यकता है (आधुनिक PHP 8 एट्रीब्यूट्स को सपोर्ट करने के लिए)। यदि आप PHP के पुराने वर्जन का उपयोग कर रहे हैं, तो आपको लाइब्रेरी के 3.x वर्जन की आवश्यकता होगी, लेकिन PHP 8+ पर अपग्रेड करने और Swagger-PHP के नवीनतम वर्जन (4.x) का उपयोग करने की दृढ़ता से अनुशंसा की जाती है।

3. त्वरित शुरुआत - न्यूनतम कार्यशील उदाहरण

आइए एक सरल कंट्रोलर बनाएँ जिसमें एक एंडपॉइंट हो और उसके लिए OpenAPI स्पेसिफिकेशन जनरेट करें।

चरण 1: फ़ाइल बनाएँ src/Controllers/UserController.php

<?php

namespace App\Controllers;

use OpenApi\Attributes as OA;

class UserController
{
    #[OA\Get(
        path: '/api/users/{id}',
        summary: 'आईडी द्वारा उपयोगकर्ता प्राप्त करें',
        tags: ['Users']
    )]
    #[OA\Parameter(
        name: 'id',
        in: 'path',
        required: true,
        schema: new OA\Schema(type: 'integer')
    )]
    #[OA\Response(
        response: 200,
        description: 'सफल प्रतिक्रिया',
        content: new OA\JsonContent(
            properties: [
                new OA\Property(property: 'id', type: 'integer'),
                new OA\Property(property: 'name', type: 'string'),
                new OA\Property(property: 'email', type: 'string')
            ]
        )
    )]
    public function getUser(int $id): array
    {
        // यहाँ डेटाबेस से उपयोगकर्ता प्राप्त करने का लॉजिक होना चाहिए
        return [
            'id' => $id,
            'name' => 'राहुल शर्मा',
            'email' => 'rahul@example.com'
        ];
    }
}

चरण 2: स्पेसिफिकेशन जनरेट करने के लिए स्क्रिप्ट बनाएँ generate-docs.php

<?php

require_once __DIR__ . '/vendor/autoload.php';

use OpenApi\Generator;

// उस डायरेक्टरी को निर्दिष्ट करें जहाँ एनोटेशन वाले हमारे कंट्रोलर हैं
$openapi = Generator::scan(['src/Controllers']);

// स्पेसिफिकेशन को JSON फ़ाइल में सेव करें
file_put_contents('openapi.json', $openapi->toJson());

echo "OpenAPI स्पेसिफिकेशन सफलतापूर्वक जनरेट हो गई है: openapi.json\n";

चरण 3: स्क्रिप्ट चलाएँ

php generate-docs.php

इसके बाद, आपके प्रोजेक्ट में openapi.json फ़ाइल बन जाएगी जिसमें आपके API का पूरा OpenAPI स्पेसिफिकेशन होगा। आप इस फ़ाइल को Swagger UI में लोड करके इंटरैक्टिव डॉक्यूमेंटेशन देख सकते हैं।

4. मुख्य एनोटेशन और उनके उपयोग

Swagger-PHP में कई प्रकार के एनोटेशन उपलब्ध हैं। यहाँ कुछ सबसे महत्वपूर्ण हैं:

• @OA\Get, @OA\Post, @OA\Put, @OA\Delete: HTTP मेथड को परिभाषित करते हैं।
• @OA\Parameter: पथ, क्वेरी, हेडर या कुकी पैरामीटर को परिभाषित करता है।
• @OA\Response: विभिन्न HTTP स्टेटस कोड के लिए रिस्पॉन्स को परिभाषित करता है।
• @OA\Schema: डेटा मॉडल (जैसे JSON ऑब्जेक्ट) को परिभाषित करता है।
• @OA\Property: स्कीमा के अंदर गुणों को परिभाषित करता है।
• @OA\Tag: एंडपॉइंट को समूहित करने के लिए टैग को परिभाषित करता है।

इन एनोटेशन का उपयोग करके, आप अपने API के हर पहलू को विस्तार से डॉक्यूमेंट कर सकते हैं, जिससे डेवलपर्स के लिए आपके API को समझना और उपयोग करना बहुत आसान हो जाता है।