백엔드 개발자라면 무조건 알아야 하는 API명세서, ERD 작성법!
인데 나만 몰랐다...
이번 개인과제의 0단계 미션이라 기회삼아 열심히 시도해보았다.
API 명세서란?
API명, 요청 값(파라미터), 반환 값, 인증/인가 방식, 데이터 및 전달 형식 등 API를 정확하게 호출하고 그 결과를 명확하게 해석하는데 필요한 정보들을 일관된 형식으로 기술한 것을 의미.
예전에 미니프로젝트할 때 다른 팀원분이 작성해주신 API 명세이다.
이걸 참고하여 이번에 작성하려고 하는데 제일 막막했던 건 툴이다.
이번에 프로젝트 root(최상위) 경로의 README.md에 작성하라고 되어있고, 추천 툴로는 Postman이라고 되어있다. 위처럼 Notion에 표로 작성된 API 명세만 봤왔기 때문에 표로 만들고 싶은데 어느 툴로 해야할까 고민을 했다.
실무에선 swagger라는 툴을 많이 사용한다고 한다. 예시를 보여주셨는데 깔끔하고 보기 좋았다.
어쨌든 정해진 건 없다고 하셨으니 나는 프로젝트에 README.md 파일에 직접 작성하기를 택했다.
### API 명세서
| 기능 | Method | URL |request|response|
|----------|--------|--------------------|---|---|
| 일정 등록 | POST | /api/scheduler |테스트3|테스트3|
| 일정 조회 | GET | /api/scheduler/{id} |테스트3|테스트3|
| 일정 목록 조회 | GET | /api/scheduler |테스트3|테스트3|
| 일정 수정 | PUT | /api/scheduler/{id} |테스트3|테스트3|
| 일정 삭제 | DELETE | /api/scheduler/{id} |테스트3|테스트3|이렇게 intelij에서 작성한 후 Github에 올리니 README.md는 왜인지 push가 안되길래 웹에서 바로 복붙해서 업로드하니 이렇게 나왔다.
이렇게 작성되는 거면 바로 깃허브에서 작성할걸... ㅎ
어쨌든 표 모양으로 API 명세서 작성하기 성공이다!(request랑 response는 수정 필요!)
ERD란?
ERD(Entity Relationship Diagram)
구현해야 할 서비스의 영역별로 필요한 데이터를 설계하고 각 영역간의 관계를 표현하는 방법.
ERD 작성할 때 다음과 같은 항목들을 넣는다.
Entity(개체): 사람, 물체, 개념
Relationship(관계): Entity-Entity를 연결해주는 관계
Attribute(속성): 사람이라면 키, 몸무게, 성별같은 속성
ERD 작성도 툴이 고민이 됐는데, ERD Cloud랑 lucidchart 중 더 간단하고 직관적인 ERD Cloud를 선택했다.
일정관리 앱 서버를 만드는 프로젝트라 스케줄러 개체만 우선 필요해보여 이렇게 만든 후 이를 토대로 테이블 생성에 필요한 query를 작성하였다.
CREATE TABLE IF NOT EXISTS SCHEDULER
(
schedulerId varchar(100) primary key comment '일정 ID',
username varchar(100) not null comment '담당자명',
password int not null comment '비밀번호',
contents varchar(100) not null comment '할일',
createDate datetime not null comment '작성일',
updateDate datetime not null comment '수정일'
);
테이블이 잘 만들어진 것을 볼 수 있다.
이렇게 API명세서, ERD를 작성해 SQL작성까지 해보았다. 처음 하니 쉬운게 하나 없다. 하지만 점차 반복할수록 익숙해지고 바로바로 끝내는 업무가 되기를 . 내일부터는 이를 토대로 CRUD 코드 구현을 한다. 아자!
+수정본
정말 부끄럽지만 이게 내 첫 API명세서와 ERD이다.
사실 깔끔하게 더 고치고 싶지만 이 놈들 작성에 더 시간을 쓰기엔 앞둔 과제가 너무 어마어마했다. 그래서 이정도 마무리하고 이걸 기반으로 SQL을 작성하고 코드를 구현했다. 근데 확실히 이렇게 고민해서 미리 작성을 해놓으니까 처음에 코드 짤 때 훨씬 편리했다. 누군가와 협업할 때는 진짜 필수겠구나 생각이 들었다.
create table SCHEDULER
(
id bigint auto_increment comment '일정 ID'
primary key,
username varchar(100) not null comment '담당자명',
password varchar(50) not null comment '비밀번호',
contents varchar(100) not null comment '할일',
createDate datetime default CURRENT_TIMESTAMP not null comment '작성일',
updateDate datetime default CURRENT_TIMESTAMP not null comment '수정일'
);ERD를 기반으로 만든 SQL query이다.
이번 과제가 또 처음으로 MySQL을 사용한 프로젝트였다. SQL 배울 때 참 재밌게 배웠었는데 프로젝트에서 써보려고 하니까 어려웠다. DBeaver에서 연습한거랑 느낌이 왜이렇게 다른건데.. 휴 그래도 애네를 사용해서 데이터베이스를 저장하고 테이블로 바로바로 볼 수 있어서 좋다. SQL문 작성하는 법 다시 연습해야겠다.
