Swagger-PHP PHP: पूरी गाइड, उदाहरण और इंस्टॉलेशन

Swagger-PHP क्या है और इसकी आवश्यकता क्यों है?

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

इसकी आवश्यकता क्यों है?

• ऑटोमेशन: दस्तावेज़ीकरण हमेशा कोड के साथ सिंक में रहता है। एंडपॉइंट बदला? एनोटेशन अपडेट करें, और दस्तावेज़ तैयार है।
• मानकीकरण: OpenAPI REST API का वर्णन करने का एक उद्योग मानक है, जो सैकड़ों टूल्स द्वारा समर्थित है।
• फ्रंटएंड के लिए सुविधा: क्लाइंट ऐप डेवलपर Postman, Insomnia में स्पेसिफिकेशन इम्पोर्ट कर सकते हैं या क्लाइंट कोड जनरेट कर सकते हैं।
• टेस्टिंग: स्पेसिफिकेशन का उपयोग API के ऑटोमैटिक टेस्टिंग के लिए किया जा सकता है।
• इंटरैक्टिव दस्तावेज़ीकरण: Swagger UI आपको ब्राउज़र से सीधे एंडपॉइंट टेस्ट करने की सुविधा देता है।

Swagger-PHP इंस्टॉलेशन

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

composer require zircote/swagger-php

यदि आप Laravel, Symfony या किसी अन्य फ्रेमवर्क का उपयोग कर रहे हैं, तो इंस्टॉलेशन प्रक्रिया समान है। इंस्टॉलेशन के बाद, आपके प्रोजेक्ट में vendor/zircote/swagger-php फ़ोल्डर बन जाएगा।

अतिरिक्त (वैकल्पिक): दस्तावेज़ीकरण को विज़ुअलाइज़ करने के लिए आपको Swagger UI की आवश्यकता होगी। आप इसे npm के माध्यम से इंस्टॉल कर सकते हैं:

npm install swagger-ui-dist

या Swagger की आधिकारिक वेबसाइट से तैयार बिल्ड डाउनलोड कर सकते हैं।

कोड उदाहरण के साथ त्वरित शुरुआत

आइए एक सरल Todo List API बनाएं और उसके लिए दस्तावेज़ीकरण जनरेट करें।

चरण 1: अपने API के साथ index.php फ़ाइल बनाएं:

<?php
/**
 * @OA\Info(
 *     title="Todo API",
 *     version="1.0.0",
 *     description="कार्यों के प्रबंधन के लिए सरल API"
 * )
 * @OA\Server(
 *     url="http://localhost:8000",
 *     description="लोकल सर्वर"
 * )
 */

use OpenApi\Annotations as OA;

/**
 * @OA\Get(
 *     path="/tasks",
 *     summary="सभी कार्यों की सूची प्राप्त करें",
 *     @OA\Response(
 *         response=200,
 *         description="सफल प्रतिक्रिया",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/Task")
 *         )
 *     )
 * )
 */
function getTasks() {
    $tasks = [
        ['id' => 1, 'title' => 'दूध खरीदें', 'completed' => false],
        ['id' => 2, 'title' => 'लेख लिखें', 'completed' => true]
    ];
    header('Content-Type: application/json');
    echo json_encode($tasks);
}

/**
 * @OA\Post(
 *     path="/tasks",
 *     summary="नया कार्य बनाएं",
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(ref="#/components/schemas/TaskInput")
 *     ),
 *     @OA\Response(
 *         response=201,
 *         description="कार्य बनाया गया",
 *         @OA\JsonContent(ref="#/components/schemas/Task")
 *     )
 * )
 */
function createTask() {
    // कार्य बनाने का लॉजिक
    echo json_encode(['id' => 3, 'title' => 'नया कार्य', 'completed' => false]);
}

/**
 * @OA\Schema(
 *     schema="Task",
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 * @OA\Schema(
 *     schema="TaskInput",
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 */

// सरल रूटिंग
$uri = $_SERVER['REQUEST_URI'];
$method = $_SERVER['REQ