# Show GN: itdoc - Swagger 없이 정확한 Node.js API 문서 만들어 보세요

> Clean Markdown view of GeekNews topic #21278. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=21278](https://news.hada.io/topic?id=21278)
- GeekNews Markdown: [https://news.hada.io/topic/21278.md](https://news.hada.io/topic/21278.md)
- Type: show
- Author: [penekhun](https://news.hada.io/@penekhun)
- Published: 2025-06-04T22:35:29+09:00
- Updated: 2025-06-04T22:35:29+09:00
- Original source: [github.com/do-pa](https://github.com/do-pa/itdoc)
- Points: 8
- Comments: 9

## Summary

**Node.js**와 **TypeScript** 개발자를 위해 테스트 코드 기반으로 **API 문서**를 자동 생성하는 오픈소스 도구를 제공합니다. 반복적이고 오류가 발생하기 쉬운 수동 문서 작업을 줄여 **협업 생산성**을 높입니다. 실제 구현과 문서 간 불일치를 최소화하여 **팀워크**를 강화합니다.

## Topic Body

### 소개  
  
**API 문서, 여전히 수동으로 작성하고 계신가요?**  
테스트만 잘 짜면, 문서가 자동으로 만들어지는 오픈소스를 만들었습니다.  
  
### 이런 분께 추천합니다  
  
- Node.js / TypeScript 백엔드 개발자  
- API 문서 작성이 귀찮고 반복적이라고 느낀 적이 있다  
- 실제 API와 문서 내용이 달라 협업이 꼬인 경험이 있다  
  
### 프로젝트 링크  
  
- Github : https://github.com/do-pa/itdoc  
- 공식 문서 : https://itdoc.kr

## Comments



### Comment 39981

- Author: kansm
- Created: 2025-06-11T22:56:11+09:00
- Points: 1

이건 문서로만 봐서 잘 이해가 안되는데.. swagger를 대체할수 있다는거죠?  
swagger보다 더 뛰어나고 보면 되는지요?? ㅎㅎ

### Comment 39982

- Author: penekhun
- Created: 2025-06-11T22:58:29+09:00
- Points: 1
- Parent comment: 39981
- Depth: 1

리드미를 좀 더 보강할 필요가 있어보이네요. 댓글 감사드립니다!  
  
https://itdoc.kr/blog/itdoc  
  
이 글 한번 읽어보시면 궁금증이 해소되실거라 믿습니다 ㅎㅎ

### Comment 39802

- Author: jhc9639
- Created: 2025-06-06T15:58:10+09:00
- Points: 1

괜찮네요ㅎㅎ

### Comment 39826

- Author: penekhun
- Created: 2025-06-07T14:26:45+09:00
- Points: 1
- Parent comment: 39802
- Depth: 1

감사합니다 🙇‍♂️

### Comment 39791

- Author: baeba
- Created: 2025-06-05T18:06:09+09:00
- Points: 1

아시겠지만..  
이런것도 있습니다.  
https://github.com/swagger-api/swagger-codegen  
  
openapi 문서포맷이면..  
node.js 코드로 생성해줍니다.  
사용해보니.. 쓸만하더군요..  
  
서버코드도 클라이언트 코드도 생성해주는데..  
일단 기존에 Rest API 관련 코딩 경험이 있으면  
도움이 많이 되지 않을까 싶어요.  
  
잘 찾아보면.. 해당 코드 포크해서 더 많이 업데이트 되고 있습니다.

### Comment 39825

- Author: penekhun
- Created: 2025-06-07T14:26:32+09:00
- Points: 1
- Parent comment: 39791
- Depth: 1

좋은 댓글 감사합니다!  
말씀해주신 도구도 훌륭하다고 생각합니다.  
  
이 기회에 itdoc과의 차이를 간단히 설명드리면,
핵심적인 차이는 바로 `Design-First` vs `Code-First`(itdoc) 접근 방식입니다.  
  
일부 팀은 OpenAPI 스펙을 먼저 설계하고 API 개발을 시작하는 Design-First 방식을 선호하고,
또 다른 팀은 실제 코드 구현을 먼저 하고 나중에 문서를 추출하는 Code-First 흐름이 더 자연스러울 수 있습니다.  
  
itdoc은 후자의 경우에 더 적합한 도구로,
테스트 기반으로 실제 동작을 바탕으로 문서를 생성하는 점이 특징입니다. 팀의 개발 방식과 선호도에 따라 적절한 도구를 선택하시면 좋을 것 같아요!

### Comment 39782

- Author: k201gun
- Created: 2025-06-05T14:03:46+09:00
- Points: 2

로고가 정말 귀엽군요

### Comment 39790

- Author: penekhun
- Created: 2025-06-05T16:58:02+09:00
- Points: 1
- Parent comment: 39782
- Depth: 1

감사합니다 😆

### Comment 39736

- Author: penekhun
- Created: 2025-06-04T22:42:35+09:00
- Points: 1

아래와 같이 사람이 읽을 수 있는 코드로 문서를 생성할 수 있습니다.  
  
```js  
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"]),  
                })  
        })  
  ....  
```