itdoc - Buat dokumentasi API Node.js yang akurat tanpa Swagger

Pengenalan

Apakah Anda masih menulis dokumentasi API secara manual?
Jika pengujiannya ditulis dengan baik, dokumentasi bisa dibuat secara otomatis. Kami membuat sebuah proyek open source untuk itu.

Direkomendasikan untuk Anda yang

• Pengembang backend Node.js / TypeScript
• Pernah merasa penulisan dokumentasi API itu merepotkan dan berulang
• Pernah mengalami kolaborasi jadi kacau karena API yang sebenarnya berbeda dengan isi dokumentasi

Tautan proyek

• Github : https://github.com/do-pa/itdoc
• Dokumentasi resmi : https://itdoc.kr

[kansm]

Ini saya kurang paham kalau cuma lihat dari dokumentasinya.. maksudnya bisa menggantikan Swagger, ya?
Apakah berarti lebih unggul daripada Swagger?? hehe

[penekhun]

Sepertinya README-nya memang perlu sedikit diperkuat. Terima kasih atas komentarnya!

https://itdoc.kr/blog/itdoc

Saya yakin kalau Anda membaca artikel ini sekali, rasa penasaran Anda akan terjawab hehe

[jhc9639]

Lumayan juga haha

[penekhun]

Terima kasih 🙇‍♂️

[baeba]

Seperti yang Anda tahu..
ada juga yang seperti ini.
https://github.com/swagger-api/swagger-codegen

kalau format dokumennya openapi..
dia akan menghasilkan kode node.js.
setelah saya coba.. ternyata cukup berguna..

baik kode server maupun kode klien bisa dibuatkan..
setidaknya kalau sudah punya pengalaman coding terkait Rest API sebelumnya
saya rasa ini akan sangat membantu.

kalau dicari lebih jauh.. fork dari kode tersebut juga banyak yang diperbarui lebih aktif.

[penekhun]

Terima kasih atas komentarnya yang bagus!
Saya juga merasa alat yang Anda sebutkan itu sangat baik.

Sebagai penjelasan singkat mengenai perbedaannya dengan itdoc pada kesempatan ini,
perbedaan utamanya adalah pendekatan Design-First vs Code-First (itdoc).

Sebagian tim lebih memilih pendekatan Design-First, yaitu merancang spesifikasi OpenAPI terlebih dahulu lalu memulai pengembangan API,
dan tim lain mungkin merasa alur Code-First lebih alami, yaitu mengerjakan implementasi kode nyata terlebih dahulu lalu mengekstrak dokumentasinya belakangan.

Untuk kasus yang kedua, itdoc adalah alat yang lebih cocok,
dengan ciri menghasilkan dokumentasi berdasarkan perilaku nyata lewat pengujian. Saya rasa akan baik jika memilih alat yang sesuai dengan cara pengembangan dan preferensi tim Anda!

[k201gun]

Logonya benar-benar lucu.

[penekhun]

Terima kasih 😆

[penekhun]

Dokumen dapat dibuat dengan kode yang bisa dibaca manusia seperti di bawah ini.

describeAPI(  
    HttpMethod.GET,  
    "/users/:userId",  
    {  
        summary: "API pengambilan pengguna",  
        tag: "User",  
        description: "API untuk mengambil informasi detail pengguna tertentu.",  
    },  
    targetApp,  
    (apiDoc) => {  
        itDoc("Jika ID pengguna yang valid diberikan, informasi detail pengguna akan ditampilkan.", async () => {  
            await apiDoc  
                .test()  
                .req()  
                .pathParam({  
                    userId: field("ID pengguna yang valid", "penek"),  
                })  
                .res()  
                .status(HttpStatus.OK)  
                .body({  
                    userId: field("ID pengguna", "penek"),  
                    username: field("Nama pengguna", "hun"),  
                    email: field("Email pengguna", "[e-mail]"),  
                    friends: field("Teman pengguna", ["zagabi", "json"]),  
                })  
        })  
  ....