itdoc - Swagger के बिना सटीक Node.js API दस्तावेज़ बनाएँ

 (github.com/do-pa)
8 पॉइंट द्वारा penekhun 2025-06-04 | 9 टिप्पणियां | WhatsApp पर शेयर करें

परिचय

क्या आप अभी भी API दस्तावेज़ हाथ से लिख रहे हैं?
अगर आप सिर्फ़ टेस्ट अच्छी तरह लिखते हैं, तो दस्तावेज़ अपने-आप बन जाते हैं—इसी के लिए हमने एक open source टूल बनाया है.

ऐसे लोगों के लिए सुझाया गया

  • Node.js / TypeScript backend डेवलपर्स
  • जिन्हें API दस्तावेज़ लिखना झंझटभरा और दोहराव वाला लगता है
  • जिन्हें वास्तविक API और दस्तावेज़ के बीच अंतर के कारण collaboration में गड़बड़ी का अनुभव हुआ है

प्रोजेक्ट लिंक

संबंधित पढ़ाई

9 टिप्पणियां

 
kansm 2025-06-11

यह सिर्फ़ दस्तावेज़ देखकर ठीक से समझ नहीं आ रहा है.. तो क्या इसका मतलब है कि यह swagger की जगह ले सकता है?
क्या इसे swagger से बेहतर मान सकते हैं?? haha
 
penekhun 2025-06-11

लगता है कि README को थोड़ा और मज़बूत करने की ज़रूरत है। टिप्पणी के लिए धन्यवाद!

https://itdoc.kr/blog/itdoc

मुझे विश्वास है कि यह लेख एक बार पढ़ने पर आपकी जिज्ञासा दूर कर देगा haha
 
jhc9639 2025-06-06

अच्छा हैhaha
 
penekhun 2025-06-07

धन्यवाद 🙇‍♂️
 
baeba 2025-06-05

जैसा कि आप जानते होंगे..
ऐसी चीज़ भी है।
https://github.com/swagger-api/swagger-codegen

अगर यह openapi document format हो..
तो यह node.js code में generate कर देता है।
इस्तेमाल करके देखा तो.. काफ़ी काम का लगा..

यह server code और client code दोनों generate कर देता है..
फ़िलहाल अगर पहले से Rest API से जुड़ा coding experience हो
तो मुझे लगता है कि यह काफ़ी मददगार हो सकता है।

ध्यान से खोजें तो.. उस code को fork करके और भी ज़्यादा update किया जा रहा है।
 
penekhun 2025-06-07

अच्छी टिप्पणी के लिए धन्यवाद!
आपने जिस टूल का ज़िक्र किया, वह भी बेहतरीन है, ऐसा मैं मानता हूँ.

इस मौके पर अगर itdoc से अंतर को संक्षेप में समझाऊँ, मुख्य अंतर Design-First बनाम Code-First (itdoc) approach का है.

कुछ टीमें पहले OpenAPI spec डिज़ाइन करके फिर API development शुरू करने वाले Design-First तरीके को पसंद करती हैं, जबकि कुछ अन्य टीमों के लिए पहले actual code implementation करना और बाद में documentation निकालना वाला Code-First flow ज़्यादा natural हो सकता है.

itdoc बाद वाले मामले में अधिक उपयुक्त टूल है, और इसकी खासियत यह है कि यह tests के आधार पर actual behavior से documentation generate करता है. टीम की development style और preference के अनुसार उपयुक्त टूल चुनें तो अच्छा रहेगा!
 
k201gun 2025-06-05

लोगो वाकई बहुत प्यारा है।
 
penekhun 2025-06-05

धन्यवाद 😆
 
penekhun 2025-06-04

नीचे की तरह, इंसानों के पढ़ने लायक code से documentation जनरेट की जा सकती है.

describeAPI(  
    HttpMethod.GET,  
    "/users/:userId",  
    {  
        summary: "사용자 조회 API",  
        tag: "User",  
        description: "특정 사용자의 상세 정보를 조회하는 API입니다.",  
    },  
    targetApp,  
    (apiDoc) => {  
        itDoc("유효한 사용자 ID가 주어지면 사용자의 상세 정보가 나온다.", async () => {  
            await apiDoc  
                .test()  
                .req()  
                .pathParam({  
                    userId: field("유효한 사용자 ID", "penek"),  
                })  
                .res()  
                .status(HttpStatus.OK)  
                .body({  
                    userId: field("유저 ID", "penek"),  
                    username: field("유저 이름", "hun"),  
                    email: field("유저 이메일", "penekhun@gmail.com"),  
                    friends: field("유저의 친구", ["zagabi", "json"]),  
                })  
        })  
  ....