📚[Backend Development] API 명세서.

✅ API 명세서 (API Specification, API Documentation)

API 명세서는 개발자 간의 API 사용 설명서이자 서로의 약속(Contract)입니다.

✅ 1. API 명세서란 무엇인가요?

API 명세서는 해당 API의 기능, 사용 방법, 요청/응답 형식, 규칙 등 API와 관련된 모든 정보를 상세하게 기록한 공식 문서입니다.

✅ 2. API 명세서는 언제 사용하나요?

소프트웨어 개발 전 과정에 걸쳐 사용됩니다.

• 기획/설계 단계 : API의 전체 구조를 미리 구상하고 정의합니다.
• 개발 단계 : 프론트엔드와 백엔드 개발자가 이 명세서를 기준으로 각자의 작업을 동시에 진행합니다.
• 테스트 단계 : API가 명세서대로 정확히 동작하는지 검증하는 기준으로 삼습니다.
• 유지보수 단계 : API를 수정하거나 기능을 추가할 때 참고하는 공식 문서로 활용됩니다.

✅ 3. API 명세서는 어떻게 사용하나요?

개발자들은 명세서를 ‘참조’하여 코드를 작성합니다.

• 백엔드 개발자 : 명세서에 정의된 대로 요청을 처리하고, 약속된 형식의 응답을 반환하는 코드를 구현합니다.
• 프론트엔드 개발자 : 명세서를 보고 서버에 어떤 URL로, 어떤 데이터를 보내야 하는지 확인하고, 서버로부터 받을 응답 데이터 구조에 맞춰 화면을 구현합니다.

✅ 4. API 명세서는 어디서 사용하나요?

개발팀 내부의 협업 도구에서 주로 사용하고 공유합니다.

• 문서화 도구 : Swagger/OpenAPI, Postman 등 API 문서를 전문적으로 관리하는 툴
• 위키/협업 툴 : Confluence, Notion, GitHub Wiki 등 팀이 공유하는 문서 공간

✅ 5. API 명세서는 왜 사용하나요?

API 명세서는 개발 과정의 불확실성을 제거하고 생산성을 극대화하기 위해 사용합니다.

• 명확한 소통 : 모든 개발자가 동일한 문서를 보고 작업하므로, “이 데이터는 어떤 형식으로 보내야 해요?”와 같은 불필요한 소통 비용이 사라집니다.
• 독립적인 병렬 개발 : 백엔드 API가 완성되지 않았더라도, 프론트엔드 개발자는 명세서만 보고 API가 완성된 것처럼 가정하고 개발을 진행할 수 있습니다.
• 의존성 감소 : 사람의 기억이나 구두 설명이 아닌, 문서에 기반하여 개발하므로 담당자가 바뀌어도 업무 공백을 최소화할 수 있습니다.

✅ 6. API 명세서는 왜 중요한가요?

• 협업 효율 증가 : 프론트엔드와 백엔드 개발자가 약속된 명세서를 기준으로 동시에 개발을 진행할 수 있어 전체 개발 시간이 단축됩니다.
• 의사소통 오류 감소 : “데이터를 어떤 형식으로 보내야 해요?”와 같은 불필요한 질문 없이, 문서를 통해 소통하여 오해를 줄입니다.
• 체계적인 API 설계 : 명세서를 작성하는 과정에서 API의 구조를 미리 고민하게 되어, 더 일관성 있고 안정적인 설계가 가능해집니다.

✅ 7. 무엇을 포함해야 하나요?

하나의 API 엔드포인트(Endpoint)는 최소한 다음 정보를 포함해야 합니다.

1. API 이름 및 설명 : 이 API가 어떤 기능을 하는지 한글로 명확하게 설명합니다. (예: 회원 가입, 특정 게시글 조회)
2. HTTP Method : GET, POST, PUT, DELETE 등 어떤 요청 방식을 사용하는지 명시합니다.
3. URL (Endpoint) : API를 호출하기 위한 고유 주소를 기입합니다. (예: /api/v1/users/{userId})
4. 요청 (Request) : 클라이언트가 서버에 보내야 할 데이터 정보를 상세히 기술합니다.
   • Header : 인증 토큰 등 요청 헤더에 담길 정보
   • Path Variable : URL 경로에 포함되는 변수 정보 (예: {userId})
   • Query Parameter : URL 뒤에 ?로 붙는 파라미터 정보 (예: /posts?page=1&size=10)
   • Body : POST 나 PUT 요청 시 전송할 JSON 데이터의 구조 (필드명, 데이터 타입, 필수 여부, 설명 등)
5. 응답 (Response) : 서버가 클라이언트에게 보내주는 결과 데이터 정보를 상세히 기술합니다.
   • 상태 코드 (Status Code) : 성공(200, 201), 실패(400, 404, 500) 등 상황별 응답 코드를 명시합니다.
   • Body : 성공 또는 실패 시 전달할 JSON 데이터의 구조 (필드명, 데이터 타입, 설명 등)

✅ 8. 어떻게 작성하나요?

• 간단한 방법 (마크다운) : Notion, Confluence, GitHub Wiki 등에 마크다운 표를 이용해 직접 작성합니다. 팀 내부에서 빠르고 간단하게 공유하기 좋습니다.
• 전문적인 방법 (OpenAPI Specification) : Swagger와 같은 도구를 사용해 작성합니다. 정해진 양식(YAML, JSON)에 따라 작성하면, 자동으로 보기좋고 체계적인 API 문서를 생성해주고 테스트 기능까지 제공하여 가장 표준적으로 사용되는 방식입니다.

✅ 9. 작성 예시 (마크 다운)

간단한 ‘특정 회원 정보 조회’ API에 대한 명세서 예시입니다.

특정 회원 정보 조회

• Description : 사용자 ID를 이용해 특정 회원의 상세 정보를 조회합니다.
• HTTP Method : GET
• URL : /api/v1/users/{userId}

Request

Response

• 성공 : 200 OK

{
    "id": 1,
    "email": "user@example.com",
    "username": "강유저",
    "createdAt": "2025-08-04T07:26:00"
}

• 실패 : 404 Not Found

{
    "errorCode": "USER_NOT_FOUND",
    "message": "해당 사용자를 찾을 수 없습니다."
}