Apidog에 대한 이야기
개인적으로 Postman의 엄청난 상위호환이라고 생각하는 Apidog에 대한 이야기
유용한 팁
정보
Apidog라는 툴을 사용해보고 느낀점에 대해 작성하는 글이에요
개인적으로Postman보다 상위호환이라고 생각해요
( 현재 나흘정도 사용해본 경험이라 해당 게시글이 완성은 아니고 계속 사용하면서 추가로 작성할 예정이에요 )
🤔 Postman의 아쉬웠던점
저는 프론트엔드 개발자라서 Postman을 직접 만들어본거는 개인 프로젝트에서 API 문서 정리를 위해서 한번 밖에 없었어요
직접 만들어보면서 너무 아쉬웠던점이 몇가지 있었어요
Schema정의 불가능Enum정의 불가능- UX가 안좋음 ( 잡렉, 보조 기능 부족 등 )
🫢 Apidog의 장점
0. 마이그레이션 쉽고 저렴함
정보
Postman에서 이전하기가 쉬워요
문서에 적힌대로 해보면 2분이면 기존 API 문서를 이전할 수 있어요
그리고 Postman보다 가격이 더 저렴하고 지원해주는 기능도 더 많아요
저희 회사는 백엔드가 4명인데 Postman이 3명까지 무료라 유료 플랜을 사용했었는데 Apidog는 무료 플랜이 4명까지 있어서 무료로도 사용할 수 있어요
1. 스키마 생성 가능
정보
위처럼 Schema가 생성이 가능해요
Schema를 생성해두면 응답 Schema에서 Schema를 그대로 사용할 수 있고, 혹은 일부로 사용할 수 있어요
그리고 description을 작성해두면 API 문서에서 읽을 수 있고, TypeScript로 변환할때 TSDoc으로도 만들어줘요
그리고 Mock을 설정해두면 목데이터를 만들때 값을 자동으로 채워줘요
( Mock은 Faker.js에서 사용하던 문법을 사용할 수 있어요 )
마지막으로 DB와 연결해서 Schema를 자동으로 생성할 수 있어요
2. 열거형 정의 가능
정보
이렇게 Enum을 정의할 수 있고, Schema나 응답 Schema에 사용할 수 있어요
그리고 description을 작성해두면 아래처럼 리스트가 보이고 Hover시 테이블을 볼 수 있어요
3. 컴포넌트
정보
자주 사용하는 응답 형태를 컴포넌트로 만들어둘 수 있어요
아직 많이 사용해보지 않아서 사용법과 의도가 맞는지 모르겠지만, 저는 자주 사용하는 400대 에러를 컴포넌트로 만들어두고 사용하고 있어요
4. Cloud Mock Server
정보
해당 기능을 사용하기 위해서는 두가지 조건이 필요해요
아래 두가지를 설정해두면 정해둔 형식에 맞게 목데이터를 만들어서 엔드포인트를 제공해줘요
- 해당 엔드포인트의 응답
Schema에 대한 목데이터 형식을 채워넣기 Cloud Mock Server를 활성화하기
5. 여러가지 기능 지원
status: 배포, 개발중, 지원종료 등의 상태 설정이 가능Maintainer: 관리자 설정 가능Tags: 태그 설정 가능- 생성자/수성자 자동 등록됨
- 응답
Schema를 설정해두고 실제 응답을 받았을때Schema와 비교해서 잘못된 부분 표시 - 브랜치 / 버전 관리 가능
🥲 Apidog의 단점
1. 데이터베이스의 스키마 가져올때 열거형 변환 안됨
아래처럼 Prisma로 만들고 DB에 생성된 것을 확인했는데 DB 연동해서 Schema를 불러와도 Enum이 생성되지 않아요
그래서 수동으로 Enum을 만들고 Schema에 연결했어요 🥲
/// 리액션 타입 enum ReactionType { /// 좋아요 👍 GOOD /// 싫어요 👎 BAD /// 불타오르다 🔥 FIRE // ... 나머지 생략 } model PostReaction { // ... 나머지 생략 /// 리액션 타입 type ReactionType }
💡 사용팁
1. Schema 일부만 사용하기
Schema를 사용하는거는 좋은데 전체말고 일부만 사용하는 경우가 더 많을거에요
그럴때는 그냥 Schema를 가져오고 사용하지 않는 컬럼은 hide를 하면 돼요
그렇게 모든 응답 Schema를 관리하면 원본 Schema가 수정되면 모든 응답 Schema도 변하기 때문에 편해요
너무 서로 의존하게 된다고 생각할수도 있지만, 어차피 원본이 바뀌면 다른것들도 따라서 바꿔야한다고 생각해요
-
원본
-
일부만 사용
2. Schema 조합하기
응답값이 항상 하나의 테이블의 데이터만 가져오지는 않을거에요
그런 경우에는 Schema Composition을 사용하면 돼요
일단 예시로 유저, 유저의 게시글, 게시글의 리액션이 있다고 가정할게요
그리고 특정 게시글을 가져올때는 게시글 + 게시글 작성자 + 게시글의 리액션들을 Join해서 가져오겠죠?
이런 경우에 Schema Composition을 사용하면 쉽게 응답 Schema를 정의할 수 있어요
이미지 하나로 표현하기에는 화면이 부족해서 텍스트로 설명할게요
0은 게시글, 1은 게시글 작성자, 2는 게시글의 리액션들이에요
1과 2가 object로 되어있는데 Schema에서 하나라도 Hide를 하면 object로 보이게 되더라고요
하지만 1은 유저 Schema를 사용하고 2는 리액션 Schema를 사용해서 원본 Schema에 의존하게 돼요
📮 레퍼런스
- API 문서 보기
- Apidog 공식 문서 - Postman 마이그레이션
- Apidog vs Postman
- Apidog 공식 문서 - Schema
- Apidog 공식 문서 - Enum 정의 방법
- Apidog 공식 문서 - Components
- Apidog 공식 문서 - Cloud Mock Server
- Apidog 공식 문서 - Schema Composition
성공연관된 포스트가 없어서 랜덤한 포스트로 대체합니다.