itdoc - Swagger olmadan doğru Node.js API dokümantasyonu oluşturun

 (github.com/do-pa)
8 puan yazan penekhun 2025-06-04 | 9 yorum | WhatsApp'ta paylaş

Giriş

API dokümantasyonunu hâlâ manuel mi yazıyorsunuz?
Sadece testleri iyi yazmanız yeterli; dokümantasyonu otomatik oluşturan bir açık kaynak proje geliştirdik.

Şunlar için önerilir

  • Node.js / TypeScript backend geliştiricileri
  • API dokümantasyonu yazmanın sıkıcı ve tekrarlı olduğunu düşünenler
  • Gerçek API ile doküman içeriğinin farklı olması nedeniyle iş birliğinin aksadığı bir deneyim yaşayanlar

Proje bağlantıları

İlgili okumalar

9 yorum

 
kansm 2025-06-11

Bunu yalnızca dokümantasyona bakarak pek anlayamıyorum.. swagger’ın yerini alabileceği anlamına mı geliyor?
swagger’dan daha üstün olduğunu düşünüp öyle mi bakmalıyız?? haha
 
penekhun 2025-06-11

Readme'yi biraz daha güçlendirmek gerekiyor gibi görünüyor. Yorumunuz için teşekkürler!

https://itdoc.kr/blog/itdoc

Bu yazıyı bir kez okursanız merak ettiklerinizin giderileceğine inanıyorum haha
 
jhc9639 2025-06-06

Güzelmiş haha
 
penekhun 2025-06-07

Teşekkürler 🙇‍♂️
 
baeba 2025-06-05

Bildiğiniz gibi...
Böyle bir şey de var.
https://github.com/swagger-api/swagger-codegen

Eğer openapi belge formatıysa...
Node.js kodu olarak üretiyor.
Kullandığımda... gayet işe yarar buldum.

Hem sunucu kodunu hem de istemci kodunu üretiyor...
Özellikle mevcut Rest API geliştirme deneyiminiz varsa
çok yardımcı olabilir diye düşünüyorum.

İyi bakarsanız... ilgili kodun fork edilip çok daha fazla güncellendiğini de görebilirsiniz.
 
penekhun 2025-06-07

Güzel yorumunuz için teşekkür ederim!
Bahsettiğiniz aracın da harika olduğunu düşünüyorum.

Bu vesileyle, itdoc ile arasındaki farkı kısaca açıklayayım:temel fark, Design-First ile Code-First (itdoc) yaklaşımıdır.

Bazı ekipler önce OpenAPI spesifikasyonunu tasarlayıp ardından API geliştirmeye başlamayı tercih eden Design-First yaklaşımını benimserken,başka ekipler için önce gerçek kodu uygulayıp daha sonra dokümantasyonu çıkarmak anlamına gelen Code-First akışı daha doğal olabilir.

itdoc ise ikinci durumda daha uygun bir araçtır;test tabanlı olarak gerçek çalışma davranışına dayanıp dokümantasyon üretmesiyle öne çıkar. Ekibin geliştirme tarzına ve tercihine göre uygun aracı seçmeniz iyi olacaktır!
 
k201gun 2025-06-05

Logosu gerçekten çok sevimli.
 
penekhun 2025-06-05

Teşekkürler 😆
 
penekhun 2025-06-04

Aşağıdaki gibi insanların okuyabileceği kodlarla dokümantasyon oluşturabilirsiniz.

describeAPI(  
    HttpMethod.GET,  
    "/users/:userId",  
    {  
        summary: "Kullanıcı sorgulama API'si",  
        tag: "User",  
        description: "Belirli bir kullanıcının ayrıntılı bilgilerini sorgulayan API'dir.",  
    },  
    targetApp,  
    (apiDoc) => {  
        itDoc("Geçerli bir kullanıcı ID'si verildiğinde kullanıcının ayrıntılı bilgileri döner.", async () => {  
            await apiDoc  
                .test()  
                .req()  
                .pathParam({  
                    userId: field("Geçerli kullanıcı ID'si", "penek"),  
                })  
                .res()  
                .status(HttpStatus.OK)  
                .body({  
                    userId: field("Kullanıcı ID'si", "penek"),  
                    username: field("Kullanıcı adı", "hun"),  
                    email: field("Kullanıcı e-postası", "penekhun@gmail.com"),  
                    friends: field("Kullanıcının arkadaşları", ["zagabi", "json"]),  
                })  
        })  
  ....