itdoc - Crea documentación precisa de API de Node.js sin Swagger

Introducción

¿Sigues escribiendo la documentación de API manualmente?
Si las pruebas están bien hechas, creamos un proyecto open source que genera la documentación automáticamente.

Recomendado para

• Desarrolladores backend de Node.js / TypeScript
• Quienes alguna vez sintieron que escribir documentación de API es tedioso y repetitivo
• Quienes tuvieron experiencias en las que la colaboración se complicó porque la API real y la documentación no coincidían

Enlaces del proyecto

• Github : https://github.com/do-pa/itdoc
• Documentación oficial : https://itdoc.kr

[kansm]

Esto se entiende poco con solo ver la documentación... entonces, ¿quiere decir que puede reemplazar a Swagger?
¿Y sería mejor que Swagger o así hay que verlo? jaja

[penekhun]

Parece que hace falta reforzar un poco más el README. ¡Gracias por el comentario!

https://itdoc.kr/blog/itdoc

Creo que si lees este artículo, se te aclararán las dudas jaja

[jhc9639]

Está bastante bien jaja

[penekhun]

Gracias 🙇‍♂️

[baeba]

Como sabrán...
También existe esto.
https://github.com/swagger-api/swagger-codegen

Si está en formato de documentación OpenAPI...
lo genera como código de Node.js.
Lo probé... y resulta bastante útil.

Genera tanto código de servidor como de cliente...
por lo pronto, si ya tienen experiencia previa programando con APIs REST,
creo que les puede ayudar bastante.

Si buscan bien... hay forks de ese código que se siguen actualizando aún más.

[penekhun]

¡Gracias por tu buen comentario!
Creo que la herramienta que mencionaste también es excelente.

Aprovechando la ocasión, si explico brevemente la diferencia con itdoc,la diferencia clave es el enfoque Design-First vs Code-First (itdoc).

Algunos equipos prefieren el enfoque Design-First, en el que primero diseñan la especificación OpenAPI y luego comienzan el desarrollo de la API,mientras que para otros equipos puede resultar más natural un flujo Code-First, donde primero implementan el código real y después extraen la documentación.

itdoc es una herramienta más adecuada para este último caso,y se caracteriza por generar documentación basada en pruebas y en el comportamiento real. ¡Creo que sería bueno elegir la herramienta adecuada según la forma de desarrollo y las preferencias del equipo!

[k201gun]

El logo es realmente adorable.

[penekhun]

Gracias 😆

[penekhun]

Puedes generar documentación con código legible para humanos, como se muestra a continuación.

describeAPI(  
    HttpMethod.GET,  
    "/users/:userId",  
    {  
        summary: "API de consulta de usuario",  
        tag: "User",  
        description: "Esta es una API para consultar la información detallada de un usuario específico.",  
    },  
    targetApp,  
    (apiDoc) => {  
        itDoc("Si se proporciona un ID de usuario válido, se muestra la información detallada del usuario.", async () => {  
            await apiDoc  
                .test()  
                .req()  
                .pathParam({  
                    userId: field("ID de usuario válido", "penek"),  
                })  
                .res()  
                .status(HttpStatus.OK)  
                .body({  
                    userId: field("ID de usuario", "penek"),  
                    username: field("Nombre de usuario", "hun"),  
                    email: field("Correo electrónico del usuario", "[e-mail]"),  
                    friends: field("Amigos del usuario", ["zagabi", "json"]),  
                })  
        })  
  ....