itdoc - Crie uma documentação precisa para APIs em Node.js sem Swagger

Introdução

Você ainda está escrevendo documentação de API manualmente?
Criei um projeto open source que gera documentação automaticamente se você escrever bons testes.

Recomendado para quem

• Desenvolvedores de backend em Node.js / TypeScript
• Já achou a escrita de documentação de API chata e repetitiva
• Já teve problemas de colaboração porque a API real e a documentação estavam diferentes

Links do projeto

• Github : https://github.com/do-pa/itdoc
• Documentação oficial : https://itdoc.kr

[kansm]

Só lendo a documentação, isso ficou meio difícil de entender.. quer dizer que pode substituir o Swagger?
É só considerar que é melhor que o Swagger?? haha

[penekhun]

Parece que o README precisa ser reforçado um pouco mais. Obrigado pelo comentário!

https://itdoc.kr/blog/itdoc

Acredito que, se você ler este texto, suas dúvidas serão esclarecidas rsrs

[jhc9639]

Ficou legal hehe

[penekhun]

Obrigado 🙇‍♂️

[baeba]

Como você já deve saber..
existe isso também.
https://github.com/swagger-api/swagger-codegen

Se for no formato de documentação OpenAPI..
ele gera código em Node.js.
Usei e.. achei bem útil..

Ele gera tanto o código do servidor quanto o do cliente..
Então, se você já tiver experiência prévia com desenvolvimento relacionado a APIs REST,
acho que pode ajudar bastante.

Se procurar direitinho.. há forks desse código sendo atualizados ainda mais.

[penekhun]

Muito obrigado pelo ótimo comentário!
Acredito que a ferramenta mencionada por você também seja excelente.

Aproveitando a oportunidade para explicar brevemente a diferença em relação ao itdoc, a principal distinção está na abordagem Design-First vs Code-First (itdoc).

Algumas equipes preferem a abordagem Design-First, em que a especificação OpenAPI é definida primeiro e o desenvolvimento da API começa depois, enquanto para outras equipes pode ser mais natural seguir um fluxo Code-First, implementando primeiro o código real e extraindo a documentação depois.

O itdoc é mais adequado para o segundo caso, e se destaca por gerar documentação com base no comportamento real, orientado por testes. Acho que vale escolher a ferramenta mais apropriada de acordo com o modo de desenvolvimento e as preferências da equipe!

[k201gun]

O logo é realmente muito fofo.

[penekhun]

Obrigado 😆

[penekhun]

É possível gerar documentação com código legível por humanos, como abaixo.

describeAPI(  
    HttpMethod.GET,  
    "/users/:userId",  
    {  
        summary: "API de consulta de usuário",  
        tag: "User",  
        description: "Esta é uma API para consultar informações detalhadas de um usuário específico.",  
    },  
    targetApp,  
    (apiDoc) => {  
        itDoc("Quando um ID de usuário válido é fornecido, as informações detalhadas do usuário são retornadas.", async () => {  
            await apiDoc  
                .test()  
                .req()  
                .pathParam({  
                    userId: field("ID de usuário válido", "penek"),  
                })  
                .res()  
                .status(HttpStatus.OK)  
                .body({  
                    userId: field("ID do usuário", "penek"),  
                    username: field("Nome do usuário", "hun"),  
                    email: field("E-mail do usuário", "[e-mail]"),  
                    friends: field("Amigos do usuário", ["zagabi", "json"]),  
                })  
        })  
  ....