itdoc - สร้างเอกสาร API ของ Node.js ที่แม่นยำได้โดยไม่ต้องใช้ Swagger

 (github.com/do-pa)
8 คะแนน โดย penekhun 2025-06-04 | 9 ความคิดเห็น | แชร์ทาง WhatsApp

แนะนำ

คุณยังเขียนเอกสาร API แบบแมนนวลอยู่หรือเปล่า?
เราได้สร้างโอเพนซอร์สที่สามารถสร้างเอกสารอัตโนมัติได้ เพียงแค่เขียนเทสต์ให้ดี

แนะนำสำหรับคนแบบนี้

  • นักพัฒนาแบ็กเอนด์ Node.js / TypeScript
  • เคยรู้สึกว่าการเขียนเอกสาร API น่าเบื่อและต้องทำซ้ำ
  • เคยมีประสบการณ์ที่ API จริงกับเนื้อหาในเอกสารไม่ตรงกันจนทำให้การทำงานร่วมกันสะดุด

ลิงก์โปรเจกต์

บทความที่เกี่ยวข้อง

9 ความคิดเห็น

 
kansm 2025-06-11

ดูจากเอกสารอย่างเดียวแล้วยังไม่ค่อยเข้าใจเท่าไร.. หมายความว่าสามารถใช้แทน Swagger ได้ใช่ไหมครับ?
แล้วถ้าเทียบกับ Swagger ถือว่าเหนือกว่ามากกว่าใช่ไหมครับ?? 55
 
penekhun 2025-06-11

ดูเหมือนว่าคงต้องเสริม README ให้ละเอียดขึ้นอีกหน่อยนะครับ ขอบคุณสำหรับคอมเมนต์ครับ!

https://itdoc.kr/blog/itdoc

ผมเชื่อว่าถ้าลองอ่านบทความนี้ดู คำสงสัยน่าจะคลี่คลายได้ครับ 555
 
jhc9639 2025-06-06

ดีเลยครับ 555
 
penekhun 2025-06-07

ขอบคุณครับ 🙇‍♂️
 
baeba 2025-06-05

อย่างที่ทราบกัน..
มีแบบนี้ด้วยครับ
https://github.com/swagger-api/swagger-codegen

ถ้าเป็นฟอร์แมตเอกสาร openapi..
มันจะสร้างเป็นโค้ด node.js ให้ได้
ลองใช้ดูแล้ว.. ก็ใช้งานได้ดีทีเดียว..

มันสร้างได้ทั้งโค้ดฝั่งเซิร์ฟเวอร์และฝั่งไคลเอนต์..
ถ้ามีประสบการณ์เขียนโค้ดเกี่ยวกับ Rest API อยู่แล้ว
ก็น่าจะช่วยได้มากทีเดียว

ถ้าลองหาดีๆ.. จะเจอฟอร์กของโค้ดนี้ที่มีการอัปเดตมากกว่านี้อยู่ครับ
 
penekhun 2025-06-07

ขอบคุณสำหรับความคิดเห็นดีๆ ครับ!
ผมคิดว่าเครื่องมือที่คุณกล่าวถึงก็น่าสนใจมากเช่นกัน

ขออธิบายความแตกต่างกับ itdoc แบบสั้นๆ ในโอกาสนี้นะครับ
ความแตกต่างหลักอยู่ที่แนวทาง Design-First กับ Code-First (itdoc) นั่นเอง

บางทีมชอบแนวทาง Design-First ที่ออกแบบสเปก OpenAPI ก่อนแล้วค่อยเริ่มพัฒนา API ขณะที่อีกบางทีมอาจรู้สึกว่าเวิร์กโฟลว์แบบ Code-First ซึ่งเริ่มจากลงมือเขียนโค้ดจริงก่อนแล้วค่อยดึงเอกสารออกมาภายหลัง เป็นธรรมชาติมากกว่า

itdoc เหมาะกับกรณีหลังมากกว่า โดยมีจุดเด่นคือสามารถสร้างเอกสารจากการทำงานจริงบนพื้นฐานของการทดสอบได้ หวังว่าคุณจะเลือกใช้เครื่องมือที่เหมาะสมตามรูปแบบการพัฒนาและความชอบของทีมได้นะครับ!
 
k201gun 2025-06-05

โลโก้น่ารักจริง ๆ
 
penekhun 2025-06-05

ขอบคุณครับ 😆
 
penekhun 2025-06-04

ด้านล่างนี้คุณสามารถสร้างเอกสารจากโค้ดที่มนุษย์อ่านเข้าใจได้ดังนี้

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"]),  
                })  
        })  
  ....