PHP के लिए Swagger/OpenAPI जनरेशन: सर्वश्रेष्ठ टूल्स और लाइब्रेरीज़

PHP के लिए Swagger/OpenAPI जनरेशन: API डॉक्यूमेंटेशन को ऑटोमेट करें

Swagger (अब OpenAPI) RESTful API को डिस्क्राइब करने का एक स्टैंडर्ड है, जो डेवलपर्स, क्लाइंट्स और ऑटोमेटेड टूल्स को सोर्स कोड तक पहुंच के बिना सर्विस की क्षमताओं को समझने में मदद करता है। PHP डेवलपर्स के लिए, zircote/swagger-php लाइब्रेरी (जिसे पहले swagger-php के नाम से जाना जाता था) सबसे महत्वपूर्ण टूल है, जो कोड में एनोटेशन से OpenAPI स्पेसिफिकेशन ऑटोमेटिकली जनरेट करती है।

zircote/swagger-php क्या है?

यह PHP में OpenAPI स्पेसिफिकेशन जनरेट करने की मुख्य लाइब्रेरी है। यह कंट्रोलर्स, मॉडल्स और रूट्स में PHPDoc एनोटेशन को पार्स करके JSON/YAML फ़ाइल बनाती है, जिसका उपयोग इनके लिए किया जा सकता है:

• ऑटोमेटिक डॉक्यूमेंटेशन जनरेशन (Swagger UI, ReDoc)
• विभिन्न भाषाओं के लिए क्लाइंट लाइब्रेरीज़ जनरेट करना
• API टेस्टिंग (Postman, Insomnia)
• रिक्वेस्ट और रिस्पॉन्स वैलिडेशन

इंस्टॉलेशन और सेटअप

Composer के ज़रिए इंस्टॉल करें:

composer require zircote/swagger-php

Laravel (या किसी भी फ्रेमवर्क) के लिए न्यूनतम कॉन्फ़िगरेशन में कंट्रोलर में एनोटेशन बनाना शामिल है। OpenAPI एनोटेशन के साथ एक सरल कंट्रोलर का उदाहरण:

<?php

namespace App\Http\Controllers\Api;

use OpenApi\Annotations as OA;

/**
 * @OA\Info(title="My API", version="1.0.0")
 * @OA\Server(url="https://api.example.com")
 */
class UserController extends Controller
{
    /**
     * @OA\Get(
     *     path="/api/users/{id}",
     *     summary="ID के अनुसार उपयोगकर्ता प्राप्त करें",
     *     @OA\Parameter(
     *         name="id",
     *         in="path",
     *         required=true,
     *         @OA\Schema(type="integer")
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="सफल उत्तर",
     *         @OA\JsonContent(ref="#/components/schemas/User")
     *     ),
     *     @OA\Response(response=404, description="उपयोगकर्ता नहीं मिला")
     * )
     */
    public function show($id)
    {
        // लॉजिक
    }
}

स्पेसिफिकेशन जनरेट करना

OpenAPI फ़ाइल बनाने के लिए यह कमांड चलाएं:

vendor/bin/openapi src -o public/openapi.yaml

या PHP कोड का उपयोग करें:

<?php

use OpenApi\Generator;

$openapi = Generator::scan(['/path/to/project/src']);
file_put_contents('public/openapi.json', $openapi->toJson());

एडवांस्ड फीचर्स

यह लाइब्रेरी सपोर्ट करती है:

• नेस्टेड स्कीमा — एनोटेशन से ऑटोमेटिक मॉडल क्रिएशन
• एंडपॉइंट ग्रुपिंग — @OA\Tag के ज़रिए
• सुरक्षा — JWT, OAuth2 के लिए @OA\SecurityScheme
• रिक्वेस्ट उदाहरण — उदाहरणों के साथ @OA\RequestBody

एनोटेशन के साथ मॉडल का उदाहरण:

<?php

/**
 * @OA\Schema(
 *     schema="User",
 *     required={"id", "email"},
 *     @OA\Property(property="id", type="integer", format="int64"),
 *     @OA\Property(property="email", type="string", format="email"),
 *     @OA\Property(property="name", type="string"),
 *     @OA\Property(property="created_at", type="string", format="date-time")
 * )
 */
class User
{
    // प्रॉपर्टीज़
}

फ्रेमवर्क के साथ इंटीग्रेशन

Laravel के लिए darkaonline/l5-swagger पैकेज उपलब्ध है, जो ये सुविधाएं जोड़ता है:

• हर रिक्वेस्ट पर ऑटोमेटिक जनरेशन
• बिल्ट-इन Swagger UI
• config फ़ाइल के ज़रिए कॉन्फ़िगरेशन

इंस्टॉलेशन:

composer require darkaonline/l5-swagger
php artisan vendor:publish --provider="L5Swagger\L5SwaggerServiceProvider"

Symfony के लिए nelmio/api-doc-bundle का उपयोग करें।

अन्य विकल्पों से तुलना

टूल	विशेषताएं	कब उपयोग करें
zircote/swagger-php	मुख्य लाइब्रेरी, एनोटेशन-आधारित	जब आपको पूर्ण नियंत्रण चाहिए
darkaonline/l5-swagger	Laravel के लिए रैपर, Swagger UI के साथ	Laravel प्रोजेक्ट्स के लिए
nelmio/api-doc-bundle	Symfony के लिए, NelmioApiDocBundle	Symfony प्रोजेक्ट्स के लिए