Apidog 프로젝트에서 엔드포인트는 모듈(Module) → 폴더(Folder) → 엔드포인트(Endpoints)의 계층적 구조로 관리됩니다.
- 모듈은 일반적으로 비즈니스 도메인 또는 서비스별로 그룹화된 독립적인 OpenAPI 파일을 나타냅니다.
- 폴더는 모듈 내에서 기능 또는 함수별로 엔드포인트를 구성합니다.
- 엔드포인트는 실제 OpenAPI 사양 또는 API 정의입니다.
이 구조를 이해하는 것은 API를 효율적으로 구성하는 데 중요합니다.
다음은 간단한 계층 구조 예시입니다.
Apidog Project
│
├── Module: User Service (비즈니스 도메인 또는 서비스별 구분)
│ │
│ ├── Folder: User Authentication (기능 카테고리)
│ │ │
│ │ ├── Endpoint: POST /login (로그인)
│ │ └── Endpoint: POST /register (회원가입)
│ │
│ └── Folder: User Info
│ │
│ └── Endpoint: GET /users/{id} (사용자 정보 가져오기)
│
└── Module: Order Service
│
├── Folder: Order Management
│ │
│ ├── Endpoint: POST /orders (주문 생성)
│ └── Endpoint: GET /orders/{id} (주문 상세 정보 가져오기)
│
└── Folder: Payment
│
└── Endpoint: POST /payment/submit (결제 제출)Apidog에서 모듈 이해하기
프로젝트 계층 구조를 이해한 후, 다음 질문은 '모든 프로젝트에 모듈이 필요한가? 언제 새 모듈을 생성해야 하는가?'입니다.
새 프로젝트를 생성하면 Apidog는 기본 모듈을 자동으로 생성합니다. 프로젝트에 단일 백엔드 서비스 또는 소수의 엔드포인트만 포함된 경우 이 기본 모듈로 충분합니다. 그러나 여러 개의 개별 API 서비스를 관리해야 하는 경우 각 서비스에 대해 별도의 모듈을 생성할 수 있습니다.
예를 들어, 프로젝트 백엔드에는 사용자, 제품, 주문, 물류와 같은 서비스가 포함될 수 있으며, 각 서비스는 특정 도메인을 담당하고 종종 다른 서비스 URL에 배포됩니다. 이 경우, 이러한 서비스의 엔드포인트를 독립적으로 관리하기 위해 개별 모듈을 생성하는 것이 좋습니다.
폴더 트리 위의 + 버튼을 클릭하고 모듈(Module)을 선택하여 모듈을 생성할 수 있습니다.
생성되면 다른 모듈과 함께 왼쪽 프로젝트 트리에 나타나며, 폴더와 엔드포인트를 위한 자체 공간을 가집니다. 각 모듈 내에서 엔드포인트와 폴더를 자유롭게 추가할 수 있습니다.
모듈은 서로 독립적이며, 각각 자체 엔드포인트, 스키마, 컴포넌트 및 모듈 변수를 가집니다. 그러나 스키마는 모듈 간에 참조될 수 있습니다. 또한 환경 변수, 데이터베이스 연결, 공통 스크립트와 같은 프로젝트 수준 설정은 모든 모듈에서 접근할 수 있습니다.
각 모듈은 완전한 OpenAPI 사양 파일에 해당합니다. 프로젝트를 내보낼 때 OpenAPI 파일은 모듈별로 생성됩니다.
모듈 내 폴더 이해하기
모듈을 생성한 후 다음 단계는 모듈 내에서 엔드포인트를 구성하는 방법을 계획하는 것입니다.
모든 모듈은 모든 하위 폴더와 엔드포인트를 담는 루트 폴더로 시작합니다.
루트 바로 아래에 폴더를 생성하거나 기존 폴더 내에 중첩하여 생성할 수 있습니다.
폴더 구조를 설계할 때 모듈의 복잡성을 고려하십시오. 엔드포인트가 몇 개만 있는 모듈의 경우 기능별로 구성된 간단한 단일 수준 폴더로도 충분합니다. 그러나 더 복잡한 모듈의 경우 모든 것을 체계적이고 쉽게 탐색할 수 있도록 잘 구조화된 다단계 폴더를 만드는 것이 좋습니다.
예를 들어, 사용자 서비스(User Service) 모듈에는 다음과 같은 최상위 폴더가 있을 수 있습니다.
- 사용자 인증 (로그인, 등록, 비밀번호 재설정 엔드포인트용)
- 사용자 정보
- 접근 제어
하나의 폴더가 너무 커지거나 논리적으로 독립적이면 독립 실행형 모듈로 변환할 수 있습니다.
폴더 이름 옆의 ... 아이콘을 클릭하고 ...더보기(More) > 새 모듈로 변환(Convert to a new Module)을 선택하십시오. 이렇게 하면 프로젝트 구조가 확장됨에 따라 잘 정리된 상태를 유지하는 데 도움이 됩니다.
모듈의 환경 관리 및 구성
구조화된 엔드포인트 외에도 각 모듈은 일반적으로 다른 서비스 주소 또는 배포 환경에 해당합니다. 이러한 설정은 환경 관리에서 쉽게 구성할 수 있습니다.
환경 관리 설정에서 각 모듈의 기본 URL을 별도로 구성할 수 있습니다. 예를 들어, 테스트 환경(Test Environment)에서:
- 사용자 서비스(User Service) →
http://user-service:8001 - 주문 서비스(Order Service) →
http://order-service:8002
환경을 전환할 때 Apidog는 각 모듈의 기본 URL을 자동으로 업데이트합니다. 예를 들어, 개발 환경에서 테스트 환경으로 전환할 때 사용자 서비스 모듈의 기본 URL은 http://localhost:8001에서 http://user-service:8001로 변경되고, 주문 서비스 모듈의 기본 URL은 http://localhost:8002에서 http://order-service:8002로 변경됩니다.
환경 변수는 모든 모듈에서 공유되며 환경 간에 다른 설정을 저장하는 데 가장 적합합니다. 반대로 모듈 변수는 각 모듈에 고유하며(예: 자체 API 키 또는 토큰) 해당 모듈 내의 모든 엔드포인트에서 사용할 수 있습니다.
스키마 관리 및 재사용
효율적인 스키마 관리는 중복을 방지하고 모듈 전반에 걸쳐 일관성을 보장하는 데 도움이 됩니다.
각 모듈에는 자체 스키마 관리 섹션이 있으며, 여기서 비즈니스 관련 데이터 구조를 정의하고 유지 관리할 수 있습니다. 이러한 스키마는 모듈 내에서 재사용하거나 다른 모듈에서 참조할 수 있습니다.
예를 들어, 사용자 서비스(User Service) 모듈은 사용자 관련 스키마를 정의합니다. 주문 서비스(Order Service) 모듈은 주문 관련 스키마를 정의합니다. 주문 서비스가 사용자 정보를 참조해야 하는 경우, 사용자 서비스의 스키마를 단순히 재사용할 수 있으며 다시 만들 필요가 없습니다.
Postman에서 Apidog로: 가져온 컬렉션 및 엔드포인트 구성
팀에서 이전에 Postman을 사용했다면 기존 컬렉션과 엔드포인트를 Apidog로 쉽게 마이그레이션할 수 있습니다.
가져오기 중:
- 각 Postman 컬렉션은 모듈이 됩니다.
- 폴더 구조가 자동으로 매핑됩니다.
- 엔드포인트와 스키마가 보존됩니다.
이를 통해 익숙한 API 구조를 유지하면서 Apidog의 모듈식 시스템을 활용할 수 있습니다.
결론
명확한 모듈을 정의하고, 폴더를 구성하며, 스키마를 재사용함으로써 Apidog 프로젝트를 깔끔하고 확장 가능하며 협업하기 쉽게 유지할 수 있습니다.
Apidog의 모듈식 설계는 팀이 더 빠르게 작업하고, 혼란을 피하며, 복잡한 API를 설계부터 문서화, 테스트까지 더 효율적으로 관리하는 데 도움이 됩니다.