📚[Backend Development] API 명세서 개발 과정 5단계

API 명세서 설계는 요구사항 분석부터 시작하여 점진적으로 구체화하는 순서로 진행됩니다.

✅ 1. 요구사항 분석 및 기능 정의.

가장 먼저 ‘무엇을 만들 것인가’를 정의합니다.
개발할 기능 목록을 구체적으로 작성하고, 각 기능에 필요한 데이터가 무엇인지 파악합니다.

• 산출물 : 기능 목록 (예: 상품 목록, 상품 검색, 주문 생성 등)

✅ 2. 리소스 식별 및 URL 설계

기능 목록을 바탕으로 API가 다룰 핵심 대상, 즉 리소스(Resource) 를 식별하고 URL을 설계합니다.
RESTful 원칙에 따라 URL은 자원의 ‘명사’를, HTTP Method는 ‘동사’를 나타내도록 구성합니다.

• 산출물 : API 엔드포인트 목록 (POST /products, GET /products, PATCH /products/{productId} 등)

✅ 3. 데이터 모델링 (Request/Response DTO 설계)

각 엔드포인트가 주고 받을 데이터의 구체적인 형태를 설계합니다.
이때 요청(Request)과 응답(Response)에 사용할 DTO(Data Transfer Object)의 필드, 데이터 타입, 필수 여부 등을 정의합니다.

• 산출물 : 각 API별 Request/Response DTO의 상세 구조

✅ 4. 상태 코드 및 에러 처리 정의

API가 성공했을 때뿐만 아니라, 다양한 실패 상황(입력값 오류, 권한 없음, 서버 오류 등)에 대한 어떤 HTTP 상태 코드를 반환하고, 어떤 에러 메시지를 보여줄지 상세하게 정의합니다.

• 산출물 : 상태 코드별 응답 형식(201 Created, 400 Bad Request, 404 Not Found 등)

✅ 5. 검토 및 문서화

완성된 설계를 바탕으로 최종 API 명세서를 작성합니다.
팀원들과 함께 검토하며 피드백을 통해 설계를 개선하고 확정합니다.
이 단계에서 Swagger/OpenAPI와 같은 도구를 사용해 문서를 작성하면 협업에 매우 효율적입니다.

• 산출물 : 최종 API 명세 문서 (Swagger, Notion, Confluence 등)