▲

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

 (github.com/do-pa)
8P by penekhun 2달전 | ★ favorite | 댓글 9개

소개

API 문서, 여전히 수동으로 작성하고 계신가요?
테스트만 잘 짜면, 문서가 자동으로 만들어지는 오픈소스를 만들었습니다.

이런 분께 추천합니다

  • Node.js / TypeScript 백엔드 개발자
  • API 문서 작성이 귀찮고 반복적이라고 느낀 적이 있다
  • 실제 API와 문서 내용이 달라 협업이 꼬인 경험이 있다

프로젝트 링크

▲
k201gun 2달전  [-]

로고가 정말 귀엽군요

답변달기
▲
penekhun 2달전  [-]

감사합니다 😆

답변달기
▲
kansm 2달전  [-]

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

답변달기
▲
penekhun 2달전  [-]

리드미를 좀 더 보강할 필요가 있어보이네요. 댓글 감사드립니다!

https://itdoc.kr/blog/itdoc

이 글 한번 읽어보시면 궁금증이 해소되실거라 믿습니다 ㅎㅎ

답변달기
▲
jhc9639 2달전  [-]

괜찮네요ㅎㅎ

답변달기
▲
penekhun 2달전  [-]

감사합니다 🙇‍♂️

답변달기
▲
baeba 2달전  [-]

아시겠지만..
이런것도 있습니다.
https://github.com/swagger-api/swagger-codegen

openapi 문서포맷이면..
node.js 코드로 생성해줍니다.
사용해보니.. 쓸만하더군요..

서버코드도 클라이언트 코드도 생성해주는데..
일단 기존에 Rest API 관련 코딩 경험이 있으면
도움이 많이 되지 않을까 싶어요.

잘 찾아보면.. 해당 코드 포크해서 더 많이 업데이트 되고 있습니다.

답변달기
▲
penekhun 2달전  [-]

좋은 댓글 감사합니다!
말씀해주신 도구도 훌륭하다고 생각합니다.

이 기회에 itdoc과의 차이를 간단히 설명드리면,
핵심적인 차이는 바로 Design-First vs Code-First(itdoc) 접근 방식입니다.

일부 팀은 OpenAPI 스펙을 먼저 설계하고 API 개발을 시작하는 Design-First 방식을 선호하고,
또 다른 팀은 실제 코드 구현을 먼저 하고 나중에 문서를 추출하는 Code-First 흐름이 더 자연스러울 수 있습니다.

itdoc은 후자의 경우에 더 적합한 도구로,
테스트 기반으로 실제 동작을 바탕으로 문서를 생성하는 점이 특징입니다. 팀의 개발 방식과 선호도에 따라 적절한 도구를 선택하시면 좋을 것 같아요!

답변달기
▲
penekhun 2달전  [-]

아래와 같이 사람이 읽을 수 있는 코드로 문서를 생성할 수 있습니다.

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"]),  
                })  
        })  
  ....
답변달기