(ProfitKey) api 명세서 작성하기 / 스웨거

프로젝트 작업에 본격적으로 코드 작업을 하기 전에 진행해야 하는 api 명세서 작성이다

 

작성해야 하는 이유는 뭘까?

1. 프론트엔드 & 백엔드 협업 원활화
   • API 구조를 미리 정리하면 프론트와 백엔드가 동시에 개발 가능
   • 불필요한 소통 감소 → 개발 속도 향상
2. 요구사항 명확화
   • 어떤 데이터를 주고받을지 정의하여 혼선을 방지
   • API 응답 형식을 통일하여 일관성 유지
3. 버그 예방 & 유지보수 용이
   • 미리 설계하면 추가 수정이나 오류 발생 가능성 감소
   • 새로운 개발자가 합류해도 API 명세서를 보고 쉽게 이해 가능
4. 테스트 & 문서화
   • API 문서를 보고 Postman 등으로 사전 테스트 가능
   • 배포 후에도 API 문서가 있으면 유지보수 및 기능 확장 용이

===> API 명세서는 협업을 원활하게 하고 개발 속도를 높이며, 유지보수까지 고려한 필수적인 문서라는 점

 

앞서 포스팅한 Confluence 글이 있는데 ,,,,

 

Confluence에 api명세서 문서를 만들어서 관리중이다.

 

이번 프로젝트에서는 마이페이지를 맡게 되었다.

(주 업무는 마이페이지이고 다른 것도 추가로 할 것)

 

초반에 작성한 api명세에서 중간중간 수정이 되고 있기도 하지만 ;;

 

결론적으로는 이렇게 갈 것 같다.

 

 

스웨거에서도 내가 작성한 api명세를 보고 테스트 할 수 있다.

 

 

Swagger는 API 명세서를 자동으로 문서화해서 UI로 제공하는 도구이다.

 

프론트와 협업하는 데에 정말 요긴하게 쓰인다.

 

프론트랑 백이랑 확실하게 구분해서 작업하는 것은 이번 프로젝트가 처음인데

 

 

• 프론트엔드 개발자는 Swagger UI에서 API 명세를 보고 요청할 데이터 형식과 응답을 확인한 후, UI를 개발합
• 백엔드 개발자는 Swagger 문서에 맞게 API를 구현하고, 수정 사항을 문서화하여 최신 API 정보를 제공

이런 흐름이라고 생각하면 될 것 같다.

 

나도 개발 후 api 테스트 할 때 사용중이다. (db체크하면서)