[신한 DS SW아카데미 / 1차 프로젝트] 데이터 명세 작성하기

⭐ 해당 프로젝트의 경우, 존재하는 레퍼런스에서 약간 변형하여 팀 프로젝트로 제작 중인 신한DS 부트캠프 1차 미니 프로젝트입니다.

🤔 Intro

• 신한 DS 부트캠프에서 1차 프로젝트를 진행하며, 페이지를 구성하는 DTO 데이터와 URL 엔드 포인트, 요청 방식등을 총정리한 데이터 명세 (API 명세)가 필요했다.

• API 명세를 포함한 이런 종류의 명세를 한 번도 짜본 적이 없기에 개인 스터디 및 명세 작성을 진행하였다. 이 내용을 여기에 정리해보려고 한다.

😀 Start!

목표

• API 명세의 필요성과 작성 방법에 대해 공부한다.
• API 명세 (우리 1차 프로젝트의 경우, REST API 통신이 아닌 MVC + JSP 구조이기에 여기서는 “데이터 명세”라고 칭하겠다.)를 작성한다.

API란?

• API는 서버와 클라이언트가 데이터를 주고 받을 수 있도록 도움을 주는 매개체라고 정의할 수 있다.
• API를 사용하기 위해서 사용자와 서버와 클라이언트는 몇 가지 약속을 따라야 한다.
  • 메세지의 데이터 형식은 무엇이고, 글자 수 제한이 있다면 몇 자 인지, 어떤 방식으로 데이터가 전달되어야 하는지, 요청에 대한 결과는 어떤 형식으로 확인할 수 있는지 등과 같은 약속을 예로 들 수 있다.
  • 이 약속을 바로 API 문서에서 한다.

API 문서 구성

• API 명세서는 다음과 같은 것을 포함하는 것이 좋다.
  • API가 어떤 동작을 하는지
  • 어떤 목적에서 API가 탄생했는지
  • API를 사용하기 전에 수행해야 할 사전 작업이 있는지 등의 충분한 개념 설명이 담긴 ‘개요’와 API 사용 시퀀스를 설명한 ‘시작 가이드’도 준비하는 것이 좋다.

API 문서의 개요

• API 문서의 개요에는
  • API 소개
  • 개발 배경
  • 비즈니스 목적
  • 공통 요청(Request) 및 응답(Reponse)형식, 공통 에러 타입 등 전반적인 API 소개와 동작 설명을 포함하면 좋다.

API 문서의 공통 요청/응답 형식

• 응답 형식에는….

  • API 요청시 사용 데이터를 ‘applicatoin/json’으로 제한했거나, 또는 ‘application/x-www-form-urlencode’로 표현된 데이터를 허용하는지…등도 포함하면 좋다.

• 응답 역시….

  • success시에는 어떤 응답이 오는지
  • fail시에는 어떤 응답이 오는지 등을 상태코드나 필드 등 자유로운 방식으로 구성이 가능하다.
  • 나의 경우는 주로 명세를 만들 때 다음과 같은 형태를 선호하는 편이다.

  {"code" : 200}
  

• 공통 에러

  • 만약 API간 공통되는 에러 코드가 존재한다면, 문서의 한 섹션에 에러코드를 모아두고 관리하는 것이 효율적이다.

API 레퍼런스

Request Syntax

• API의 형태, 구조에 대한 정의를 나타낸다.
• API가 어떤 메서드를 사용하는지,
• 요청 URL의 형태는 무엇인지,
• 그리고 코드 예제가 함께 제공되면 좋다.

Request Header

• 요청에 대한 추가 정보를 담고 있는 부분이다.
• 메시지의 총 길이(Content-Length), 형식(Content-Type) 등이 Header에 포함될 수 있다.
• 소셜 로그인을 이용할 경우, 앞에서 발급받은 인증 정보(token)을 header에 작성하기도 한다.

Request Element

• 해당 요청의 실제 메세지/내용이 해당된다.
• Request Element에는 API를 요청하기 위한..
  • 파라미터와 파라미터 유형
  • 필수 여부
  • 설명, 제약 사항 등이 제공되어야 한다.
  • 간혹 Element가 없는 요청도 있는데, 대표적으로 정보를 불러올때 사용하는 GET 메서드가 바로 그것이다.

😗 [실습] 데이터 명세 작성해보기

• 이제 학습한 내용을 바탕으로 데이터 명세를 작성해보자.
• 현재 프로젝트의 경우, API 방식이 아니라서 명세가 필요한 부분들이 약간 다르다.
• 그러나, 위의 명세에 필요한 “내용”들을 바탕으로, 명세에 들어가야 할 내용들을 다음과 같이 정리하였다.
  1. 요청 URL (엔드포인트)
  2. 로그인 세션 필요 여부
  3. 요청 방식
  4. DTO에 필요한 데이터 ( API 명세에서 Response로 뿌려주는 데이터의 역할을 한다.)
  5. Mapper 쿼리
  6. 화면 명세

데이터 명세표 (user)

• 현재, 내가 속한 기능인 “user” 기능의 데이터 명세표는 다음과 같다.

  

  • [2025-06-16] 기준, 외부 API 연동 및 AJAX 요청 관련 API 빼고는 전부 완성된 상태이다.
  • 데이터 명세는 user / store / admin 별로 테이블을 나눠서 보기 편하게 구성했다.
  • 또한, endpoint의 경우, 각 기능별로 구성해서 user가 이용할 수 있는 기능의 경우 /user/…로 시작하게끔 맞춰두었다.

요청정보

• 상세 페이지의 맨 첫 단에는 요청 정보를 정리했다.
• 요청 방식, url, 포워딩 방식을 한 눈에 보기 좋게 정리한 페이지 요약본이다
• 상세 설명에는 해당 페이지에 대한 중요 시퀀스를 적어두었다.

Mapper (DTO 구성 요소)

• DTO를 구성하기 위해 각 테이블에서 가져와야 하는 모든 컬럼들을 정리한 표이다.
• 차후 Mapper 쿼리 작성을 쉽게 하기 위해 각 테이블별로 어떤 정보를 가져와야 하는지를 토글로 정리했다.
• 이외에도, DB에는 없지만 프론트를 구성하기 위해 있으면 좋은 추가 정보도 같이 정리해두었다.
• Mapper 쿼리의 경우는 아직 만들지 않았는데, 해당 페이지에 같이 정리할 예정이다.

화면 명세

• 피그마를 보고 컬럼들을 정리하기는 하였지만, 혹시나 놓친 정보가 있을까봐 요소별로 쓰이는 컬럼들을 다음과 같이 정리하였다.
• 이를 통해 개발 시 좀 더 꼼꼼하고 편리하게 data들을 구성할 수 있다:)

📌 참고 문서

• 카카오엔터프라이즈 기술 블로그
• 티스토리 블로그