स्वैगर इंटरैक्टिव और उपयोगकर्ता के अनुकूल एपीआई प्रलेखन बनाने के लिए एक स्वतंत्र, खुला स्रोत ढांचा है। यह इंटरैक्टिव वेब पेज बनाता है जो आपको विभिन्न इनपुट के साथ एपीआई का परीक्षण करने की अनुमति देता है।

स्वैगर JSON और XML दोनों पेलोड का समर्थन करता है। यह जो दस्तावेज़ बनाता है वह डेवलपर्स और गैर-डेवलपर्स के उपयोग के लिए उपयुक्त है।

आप अपने आईडीई को छोड़े बिना, साधारण डेकोरेटर का उपयोग करके स्वैगर के माध्यम से अपने NestJS वेब एपीआई का दस्तावेजीकरण कर सकते हैं।

चरण 1: एपीआई बनाना

शुरू करने से पहले, आपको एक डेमो एपीआई बनाना होगा जो स्वैगर इसके दस्तावेज़ीकरण को उत्पन्न करेगा।

आप NestJS CLI का उपयोग करके शुरू से ही डेमो API जेनरेट करेंगे।

सबसे पहले, एक नया NestJS प्रोजेक्ट चलाकर जनरेट करें:

घोंसला नया <नाम-का-आपकी-परियोजना>

फिर, निर्देशिका को अपने पहले से बनाए गए प्रोजेक्ट में चलाकर बदलें:

सीडी <नाम-का-आपकी-परियोजना>

इसके बाद, आप चलकर CLI के साथ एक REST API जनरेट करेंगे:

नेस्ट जनरेट रिसोर्स डेमो --नो-स्पेक

आपको एक प्रश्न दिखाई देगा, जिसमें पूछा जाएगा, "आप किस परिवहन परत का उपयोग करते हैं?" चुनते हैं बाकी एपीआई।

आप एक अन्य प्रश्न पूछेंगे, "क्या आप सीआरयूडी प्रवेश बिंदु उत्पन्न करना चाहेंगे?" टाइप यू और हिट प्रवेश करना.

उपरोक्त आदेश उत्पन्न करता है एक पूरी तरह कार्यात्मक आरईएसटी एपीआई सीआरयूडी एंडपॉइंट्स के साथ और यूनिट टेस्ट फाइलों के बिना। इसलिए --नो-स्पेक उपरोक्त आदेश में ध्वज।

चरण 2: स्वैगर स्थापित करें

स्वैगर और उसके एक्सप्रेस यूआई पुस्तकालय को चलाकर स्थापित करें:

NPM इंस्टॉल--save @nestjs/swagger swagger-ui-express

चरण 3: स्वैगर कॉन्फ़िगर करें

अपने में main.ts फ़ाइल, आयात स्वैगरमॉड्यूल तथा दस्तावेज़ निर्माता से @nestjs/स्वैगर.

DocumentBuilder आधार दस्तावेज़ की संरचना में सहायता करता है। यह कई तरीके प्रदान करता है जिन्हें आप एक साथ श्रृंखलाबद्ध कर सकते हैं और इसके साथ बंद कर सकते हैं बनाना तरीका।

ये विधियां शीर्षक, विवरण और संस्करण जैसी कई विशेषताओं के कॉन्फ़िगरेशन को सक्षम करती हैं।

बनाओ कॉन्फ़िग आपके में वस्तु चर बूटस्ट्रैप इस तरह कार्य करें:

स्थिरांक विन्यास = नया दस्तावेज़बिल्डर ()
 .setTitle ('डेमो एपीआई')
 .setDescription('एक डेमो एपीआई साथ सीआरयूडी कार्यक्षमता')
 .सेटवर्जन ('1.0')
 ।बनाना();

DocumentBuilder का एक नया उदाहरण एक आधार दस्तावेज़ बनाता है जो से मेल खाता है ओपनएपीआई विशिष्टता. फिर आप इस उदाहरण का उपयोग शीर्षक, विवरण और संस्करण को उनके उपयुक्त तरीकों के माध्यम से सेट करने के लिए कर सकते हैं।

इसके बाद, आपको मूल दस्तावेज़ का उपयोग करके परिभाषित सभी HTTP मार्गों के साथ एक पूर्ण दस्तावेज़ बनाना होगा।

ऐसा करने के लिए, कॉल करें दस्तावेज़ बनाएँ स्वैगर मॉड्यूल पर विधि। createDocument दो तर्क स्वीकार करता है: एक एप्लिकेशन इंस्टेंस और एक स्वैगर विकल्प ऑब्जेक्ट। इस कॉल के परिणाम को बाद में उपयोग के लिए एक चर में संग्रहीत करें:

स्थिरांकदस्तावेज़ = SwaggerModule.createDocument (ऐप, कॉन्फिग);

इसके बाद, कॉल करें स्थापित करना स्वैगर मॉड्यूल पर विधि। सेटअप विधि तीन तर्कों में लेती है:

  1. स्वैगर यूआई पथ। परंपरा के अनुसार, आप "एपीआई" का उपयोग कर सकते हैं।
  2. एक आवेदन उदाहरण
  3. पूरा दस्तावेज़

साथ ही, सेटअप विधि एक वैकल्पिक विकल्प ऑब्जेक्ट लेती है। देखना स्वैगर दस्तावेज़ विकल्पों पर NestJS का दस्तावेज़ीकरण इसके बारे में अधिक जानने के लिए।

इस तरह:

स्वैगरमॉड्यूल.सेटअप('एपीआई', ऐप, दस्तावेज़);

अपना आवेदन शुरू करें और जाएं http://localhost:/api

आपको पृष्ठ पर प्रदर्शित स्वैगर UI देखना चाहिए।

ऊपर दी गई छवि स्वैगर यूआई का डिफ़ॉल्ट दृश्य है, जिसमें आपके नियंत्रक के सभी HTTP मार्ग परिभाषित हैं। आपको अपनी एपीआई कार्यक्षमता में फिट होने के लिए इसे अनुकूलित करने की आवश्यकता होगी।

चरण 4: एपीआई गुणों को अनुकूलित करें

डिफ़ॉल्ट रूप से, स्वैगर पूरे HTTP रूट सेक्शन को एक शीर्षक के साथ उपसर्ग करता है जो "डिफ़ॉल्ट" पढ़ता है। आप अपने नियंत्रक वर्ग की व्याख्या करके इसे बदल सकते हैं @एपीटैग डेकोरेटर और अपने पसंदीदा टैग को तर्क के रूप में पास करना।

इस तरह:

// डेमो.कंट्रोलर.ts
आयात { एपीटैग } से '@nestjs/swagger';
@एपीटैग('डेमो')
@नियंत्रक('डेमो')
निर्यात करनाकक्षा डेमोकंट्रोलर {

स्कीमा अनुभाग में आपके एपीआई में डेटा-ट्रांसफर ऑब्जेक्ट होते हैं। वर्तमान में, UI में उनकी कोई भी संपत्ति शामिल नहीं है।

UI में उनके गुण घोषित करने के लिए, बस डेकोरेटर जोड़ें। प्रत्येक आवश्यक संपत्ति के साथ एनोटेट करें @ApiProperty डेकोरेटर के साथ वैकल्पिक गुणों की व्याख्या करें @ApiPropertyOptional डेकोरेटर

उदाहरण के लिए:

// create-demo.dto.ts
आयात { एपीप्रॉपर्टी, एपीप्रॉपर्टीऑप्शनल } से '@nestjs/swagger';
निर्यात करनाकक्षा CreateDemoDto {
@ApiProperty({
प्रकार: डोरी,
 विवरण: 'यह एक आवश्यक संपत्ति है',
 })
 संपत्ति: डोरी;
@ApiPropertyOptional({
प्रकार: डोरी,
 विवरण: 'यह एक वैकल्पिक संपत्ति है',
 })
 वैकल्पिक संपत्ति: डोरी;
}

@ApiProperty और @ApiPropertyOptional सज्जाकार प्रत्येक एक विकल्प ऑब्जेक्ट स्वीकार करते हैं। वह वस्तु नीचे दी गई संपत्ति का वर्णन करती है।

ध्यान दें कि विकल्प ऑब्जेक्ट जावास्क्रिप्ट का उपयोग करता है, टाइपस्क्रिप्ट का नहीं। इसलिए जावास्क्रिप्ट प्रकार की घोषणाएं (यानी स्ट्रिंग, स्ट्रिंग नहीं)।

डेटा-ट्रांसफर ऑब्जेक्ट के गुणों की व्याख्या करना स्कीमा अनुभाग में अपेक्षित डेटा का एक उदाहरण जोड़ता है। यह अपेक्षित डेटा के उदाहरण के साथ संबद्ध HTTP रूट को भी अपडेट करता है।

चरण 5: एपीआई प्रतिक्रियाएँ सेट करें

अपने नियंत्रक वर्ग में, का उपयोग करें @ApiResponse सज्जाकार प्रत्येक HTTP मार्ग के लिए सभी संभावित प्रतिक्रियाओं का दस्तावेजीकरण करने के लिए। प्रत्येक समापन बिंदु के लिए, विभिन्न @ApiResponse सज्जाकार अपेक्षित प्रतिक्रियाओं के प्रकार का वर्णन करते हैं।

हमने समझाया है सामान्य HTTP प्रतिक्रियाएं, यदि आप उनके अर्थ से अपरिचित हैं।

@ApiResponse डेकोरेटर एक वैकल्पिक वस्तु को स्वीकार करते हैं जो प्रतिक्रिया का वर्णन करती है।

सामान्य पोस्ट प्रतिक्रियाएं

POST अनुरोध के लिए, संभावित प्रतिक्रियाओं में शामिल हैं:

  • एपीक्रिएटेड रिस्पांस, सफल 201 सृजित प्रतिक्रियाओं के लिए।
  • ApiUnprocessableEnityResponse, विफल 422 असंसाधित निकाय प्रतिक्रियाओं के लिए।
  • ApiForbiddenResponse, 403 निषिद्ध प्रतिक्रियाओं के लिए।

उदाहरण के लिए:

// डेमो.कंट्रोलर.ts
@पद()
@ApiCreatedResponse({विवरण: 'सफलतापूर्वक बनाया गया'})
@ApiUnprocessableEntityResponse({विवरण: 'खराब अनुरोध'})
@ApiForbiddenResponse({विवरण: 'अनधिकृत अनुरोध'})
 सृजन करना(@शरीर() createDemoDto: CreateDemoDto) {
वापसीयह.demoService.create (createDemoDto);
 }

सामान्य प्रतिक्रिया प्राप्त करें

GET अनुरोधों के लिए, संभावित प्रतिक्रियाओं में शामिल हैं:

  • एपीओके रिस्पांस, 200 ठीक प्रतिक्रियाओं के लिए।
  • ApiForbiddenResponse, 403 निषिद्ध प्रतिक्रियाओं के लिए।
  • ApiNotFoundResponse, 404 नहीं मिली प्रतिक्रियाओं के लिए।

उदाहरण के लिए:

// डेमो.कंट्रोलर.ts
@प्राप्त()
@ApiOkResponse({विवरण: 'संसाधन सफलतापूर्वक लौटाए गए'})
@ApiForbiddenResponse({विवरण: 'अनधिकृत अनुरोध'})
 सब ढूँढ़ो() {
वापसीयह.demoService.findAll ();
 }
@प्राप्त(':पहचान')
@ApiOkResponse({विवरण: 'संसाधन सफलतापूर्वक लौटाया गया'})
@ApiForbiddenResponse({विवरण: 'अनधिकृत अनुरोध'})
@ApiNotFoundResponse({विवरण: 'संसाधन नहीं मिला'})
 ढूँढो एक(@परम('मैंने किया: डोरी) {
वापसीयह.demoService.findOne(+id);
 }

सामान्य पैच और अद्यतन प्रतिक्रियाएं

पैच और अद्यतन अनुरोधों के लिए, संभावित प्रतिक्रियाओं में शामिल हैं:

  • एपीओके रिस्पांस, 200 ठीक प्रतिक्रियाओं के लिए।
  • ApiNotFoundResponse, 404 नहीं मिली प्रतिक्रियाओं के लिए।
  • एपीअनप्रोसेसिबलएंटिटी रिस्पॉन्स, विफल 422 असंसाधित निकाय प्रतिक्रियाओं के लिए।
  • ApiForbiddenResponse, 403 निषिद्ध प्रतिक्रियाओं के लिए।

उदाहरण के लिए:

// डेमो.कंट्रोलर.ts
@पैबंद(':पहचान')
@ApiOkResponse({विवरण: 'संसाधन सफलतापूर्वक अपडेट किया गया'})
@ApiNotFoundResponse({विवरण: 'संसाधन नहीं मिला'})
@ApiForbiddenResponse({विवरण: 'अनधिकृत अनुरोध'})
@ApiUnprocessableEntityResponse({विवरण: 'खराब अनुरोध'})
 अपडेट करें(@परम('मैंने किया: डोरी, @शरीर() UpdateDemoDto: UpdateDemoDto) {
वापसीयह.demoService.update(+id, updateDemoDto);
 }

आम DELETE प्रतिक्रियाएँ

DELETE अनुरोधों के लिए, संभावित प्रतिक्रियाओं में शामिल हैं:

  • एपीओके रिस्पांस, 200 ठीक प्रतिक्रियाओं के लिए।
  • ApiForbiddenResponse, 403 निषिद्ध प्रतिक्रियाओं के लिए।
  • ApiNotFoundResponse, 404 नहीं मिली प्रतिक्रियाओं के लिए।

उदाहरण के लिए:

// डेमो.कंट्रोलर.ts
@मिटाना(':पहचान')
@ApiOkResponse({विवरण: 'संसाधन सफलतापूर्वक लौटाया गया'})
@ApiForbiddenResponse({विवरण: 'अनधिकृत अनुरोध'})
@ApiNotFoundResponse({विवरण: 'संसाधन नहीं मिला'})
 हटाना(@परम('मैंने किया: डोरी) {
वापसीयह.demoService.remove(+id);
 }

ये सज्जाकार आपके दस्तावेज़ीकरण को संभावित प्रतिक्रियाओं से भर देते हैं। आप उन्हें प्रत्येक मार्ग के साथ ड्रॉप-डाउन का उपयोग करके देख सकते हैं।

अपना दस्तावेज़ देखना

जब आपका सेटअप पूरा हो जाए, तो आप अपने दस्तावेज़ों को इस पर देख सकते हैं लोकलहोस्ट:/api. इसे आपके इंटरैक्टिव एपीआई दस्तावेज को सामने लाना चाहिए।

स्वैगर एपीआई प्रलेखन की अनिवार्यता विवरण, प्रतिक्रिया प्रकार और स्कीमा परिभाषा है। अच्छे एपीआई दस्तावेज बनाने के लिए ये बुनियादी चीजें हैं।