Swagger/OpenAPI जनरेशन PHP के लिए

Swagger/OpenAPI जनरेशन PHP के लिए: उपकरणों का संपूर्ण अवलोकन

आधुनिक वेब डेवलपमेंट में, गुणवत्तापूर्ण API दस्तावेज़ीकरण बनाना केवल एक अच्छा अभ्यास नहीं, बल्कि एक आवश्यकता बन गया है। Swagger (अब OpenAPI के नाम से जाना जाता है) RESTful API का वर्णन करने का एक मानक है, जो दस्तावेज़ीकरण, क्लाइंट SDK और टेस्ट कंसोल इंटरफ़ेस के जनरेशन को स्वचालित करने की अनुमति देता है। इस लेख में, हम विस्तार से देखेंगे कि PHP प्रोजेक्ट्स के लिए Swagger/OpenAPI का उपयोग कैसे करें, कौन सी लाइब्रेरीज़ मौजूद हैं और उन्हें सही तरीके से कैसे लागू करें।

Swagger/OpenAPI क्या है?

OpenAPI Specification (OAS) एक विशिष्टता है जो JSON या YAML प्रारूप में REST API के विवरण के मानक को परिभाषित करती है। यह अनुमति देता है:

स्वचालित रूप से इंटरैक्टिव दस्तावेज़ीकरण (Swagger UI) जनरेट करना;
विभिन्न प्रोग्रामिंग भाषाओं के लिए क्लाइंट लाइब्रेरीज़ बनाना;
अनुरोधों और प्रतिक्रियाओं की सत्यता की जाँच करना;
CI/CD पाइपलाइनों के साथ एकीकृत करना।

PHP के लिए मुख्य लाइब्रेरीज़

PHP में OpenAPI के साथ काम करने के लिए कई लोकप्रिय लाइब्रेरीज़ हैं। आइए उनमें से प्रत्येक पर विस्तार से नज़र डालें।

1. Swagger-PHP (zircote/swagger-php)

यह PHP एनोटेशन से OpenAPI विशिष्टता जनरेट करने के लिए सबसे लोकप्रिय और परिपक्व लाइब्रेरी है। यह API को सीधे कोड में वर्णित करने की अनुमति देता है, जिससे दस्तावेज़ीकरण को अद्यतित रखना आसान हो जाता है।

स्थापना:

composer require zircote/swagger-php

उपयोग का उदाहरण:

<?phpuse OpenApi\\Annotations as OA;

/** * @OA\\Info( *     title="मेरा API", *     version="1.0.0", *     description="Swagger प्रदर्शन के लिए उदाहरण API" * ) * @OA\\Server( *     url="https://api.example.com", *     description="Production server" * ) */class UserController{    /**     * @OA\\Get(     *     path="/api/users",     *     summary="उपयोगकर्ताओं की सूची प्राप्त करें",     *     @OA\\Response(     *         response=200,     *         description="सफल प्रतिक्रिया",     *         @OA\\JsonContent(type="array",     *             @OA\\Items(ref="#/components/schemas/User")     *         )     *     )     * )     */    public function getUsers()    {        // उपयोगकर्ता प्राप्त करने का तर्क    }

    /**     * @OA\\Schema(     *     schema="User",     *     type="object",     *     @OA\\Property(property="id", type="integer"),     *     @OA\\Property(property="name", type="string"),     *     @OA\\Property(property="email", type="string")     * )     */    public function userSchema()    {        // स्कीमा का वर्णन करने के लिए खाली विधि    }}

// विशिष्टता जनरेशन$openapi = \\OpenApi\\Generator::scan(['/path/to/controllers']);file_put_contents('openapi.json', $openapi->toJson());?>

2. OpenAPI-Server (thecodingmachine/openapi-server)

यह लाइब्रेरी न केवल API का वर्णन करने की अनुमति देती है, बल्कि OpenAPI विशिष्टता के आधार पर स्वचालित रूप से सर्वर कोड जनरेट करने की भी अनुमति देती है। यह Design-First डेवलपमेंट सिद्धांत का उपयोग करते समय विशेष रूप से उपयोगी है।

स्थापना:

composer require thecodingmachine/openapi-server

सर्वर जनरेशन का उदाहरण:

<?phpuse TheCodingMachine\\OpenAPI\\Server\\Builder;

// विशिष्टता लोड करना$spec = json_decode(file_get_contents('openapi.json'), true);

// सर्वर बनाना$builder = new Builder();$server = $builder->build($spec, 'App\\\\Controllers\\\\');

// अनुरोध को संसाधित करना$response = $server->handle($request);?>