API 공부하기 - api명세서와 스웨거Swagger가 뭘까 ?

프로젝트에서 슬슬 UI작업이 끝나가고, 백엔드쪽에서 완성되는 명세서를 확인하고 공부해야 할 필요가 생겼다.

우리 팀원들이 모두 출중해서,,,, 이미 프론트엔드에서 많은 경험들이 있으신데 다들,,,

그 분들께서 나누는 대화에서 생소한 단어들이 많아서.. 메모해두었다가, 혼자 이렇게 다시 공부한다 .. 📝✏️

 

이번엔 "스웨거~ 확인해보세요 / 명세서가 왜 이렇지 ?! (ㅋㅋㅋㅋ) "

하는 대화들을 듣고.. 나도 api 받아오고 해야 할 작업들이 있기에, 한번 공부해보기 !

---

프론트 vs 백엔드: 역할 먼저!

• 프론트엔드 = 사용자한테 보이는 화면 만드는 사람 
• 백엔드 = 서버에서 로그인 처리, 데이터 저장 이런 거 하는 사람

예시 상황: "로그인 화면 만들기"

너는 로그인 화면을 만들고 있어!
이제 로그인 버튼 누르면 백엔드에 정보를 보내야 해.

이때 필요한 정보!

"내가 로그인 정보를 어디로 보내야 하지?"
"어떤 형식으로 보내야 하지?"
"응답은 어떤 모양으로 오지?"

이게 전부 API 명세서에 써 있는 것.

 

1. 너는 로그인 화면을 만들었어.
   사용자가 이메일이랑 비밀번호 입력함
2. 로그인 버튼을 누르면 이렇게 요청을 보낼 거야:

fetch("https://server.com/login", {
  method: "POST",
  body: JSON.stringify({
    email: "abc@example.com",
    password: "1234"
  })
})

그런데 이 정보(주소, 메서드, 보내는 형식)를 어떻게 알아야 할까?

→ 바로 API 명세서에서 확인해!

 

📄 API 명세서에 이런 내용이 있어!

요청 URL	POST /login
요청 데이터	{"email": "string", "password": "string"}
응답 데이터	{"token": "abcd1234", "userId": 1}
실패 시	400: 비밀번호 틀림

 

이걸 보고, 아~ 이렇게 보내면 되는구나! 하고 코드 짜는 거야 🙌

 

그럼.. 🛠️ Swagger는 뭐야?

이런 API 명세서를 자동으로 웹에 보기 좋게 보여주는 도구야!

웹사이트처럼 생겼고, 버튼 눌러서 실제로 테스트도 가능해.

 정리!

• 📄 API 명세서 = 백엔드랑 통신할 때 필요한 사용 설명서
• 🔧 Swagger = 이 설명서를 보기 쉽게 웹사이트처럼 보여주는 도구
• 📱 너는 프론트엔드 개발자니까, 이걸 보고 서버랑 잘 연결하는 게 너의 일!

---

 

흐름은 알았는데 Swagger가 정확히 뭔지는 이해가 어려웠다.

---

**Swagger(스웨거)**는 백엔드 API 문서를 자동으로 만들어주는 도구야.

개발자들이 API를 더 쉽게 이해하고 사용할 수 있게 도와주는 역할을 하지.

🔍 Swagger가 뭔지 쉽게 설명해볼게!

 예를 들어서…

팀에서 백엔드 개발자가 로그인 API를 만들었다고 해보자.
프론트엔드 개발자인 너는 "어떤 주소로 요청해야 해? 어떤 데이터 보내야 해?" 이런 걸 알아야 하잖아?

이럴 때 필요한 정보가 바로 API 명세서인데, 이걸 수동으로 문서로 만들면 너무 번거롭고 틀릴 수도 있어.
Swagger는 이걸 자동으로 생성해줘! 🙌

---

📘 Swagger의 핵심 기능

📄 API 문서 자동 생성	백엔드 코드에 주석처럼 작성하면, 자동으로 웹에서 볼 수 있는 API 문서를 만들어줘
🧪 Try it out 버튼	실제로 API를 테스트할 수 있는 기능도 있어 (프론트 없이도 테스트 가능)
🔁 API 규격 공유	팀원들, 특히 프론트 개발자나 디자이너와 API 정보를 공유하기 편해

📷 Swagger UI 예시

Swagger 문서를 웹 브라우저에서 열면 이런 식으로 보여:

POST /login
Body:
{
  "email": "example@example.com",
  "password": "123456"
}

→ Try it out 버튼 누르면 실제로 테스트 가능!

 

 Swagger가 포함된 대표적인 도구

• Swagger UI: 웹에서 API 문서를 시각적으로 보여주는 도구
• Swagger Editor: Swagger 문서를 직접 편집하고 볼 수 있는 웹 에디터
• OpenAPI (구 Swagger Spec): Swagger에서 사용하는 표준 문서 형식

---