Swagger로 API 문서 자동화하기 – Go API 협업의 핵심 도구

Swagger로 API 문서 자동화하기 – Go API 협업의 핵심 도구

API를 개발할 때 가장 중요한 요소 중 하나는 명확한 API 문서 제공입니다.
이번 글에서는 Go 백엔드 프로젝트에 **Swagger (OpenAPI)**를 적용하여,

• API 사용 방법을 명확히 문서화하고
• 실시간 테스트 UI도 제공하는
  효율적인 자동 문서화 시스템을 구축해보겠습니다.

---

✅ 1. Swagger(OpenAPI)란?

Swagger는 OpenAPI 스펙을 따르는 API 문서 자동화 도구입니다.

• 엔드포인트, 파라미터, 응답 형태 등을 표준화된 형식으로 문서화
• UI를 통해 직접 테스트 가능
• 팀 협업 및 프론트엔드 연동에 필수

---

✅ 2. swag CLI 설치

반응형

먼저, Swagger 주석을 기반으로 문서를 생성해주는 **swaggo/swag**를 설치합니다.

go install github.com/swaggo/swag/cmd/swag@latest

🔁 GOPATH/bin에 설치된 경우, $PATH 설정 필요

export PATH=$PATH:$(go env GOPATH)/bin

---

✅ 3. 관련 패키지 설치

go get -u github.com/swaggo/http-swagger
go get -u github.com/swaggo/swag

---

✅ 4. main.go에 Swagger 핸들러 추가

import (
  "github.com/gorilla/mux"
  "github.com/swaggo/http-swagger"
  _ "your_project/docs" // 반드시 추가해야 swagger 문서에 반영됨
)

func main() {
  r := mux.NewRouter()

  r.PathPrefix("/swagger/").Handler(httpSwagger.WrapHandler)

  http.ListenAndServe(":8080", r)
}

---

✅ 5. 주석으로 API 문서 작성

예시: GetUsers 핸들러 위에 작성

// @Summary 사용자 목록 조회
// @Description 등록된 모든 사용자를 가져옵니다
// @Tags users
// @Produce json
// @Success 200 {array} models.User
// @Router /users [get]
func GetUsers(w http.ResponseWriter, r *http.Request) {
  ...
}

📍 모든 핸들러에 이런 식으로 주석을 달아야 문서화됩니다.

---

✅ 6. docs 디렉토리 생성 (자동)

swag init

📁 docs/swagger.json과 .go 파일들이 생성됩니다.
프로젝트 루트에 있어야 Swagger UI가 정상 작동합니다.

---

✅ 7. Swagger UI 확인

서버 실행 후 브라우저에서

http://localhost:8080/swagger/index.html

로 접속하면, 자동 생성된 API 문서 UI를 볼 수 있습니다.

---

✅ 8. 예시: POST 핸들러 문서 주석

// @Summary 유저 생성
// @Tags users
// @Accept json
// @Produce json
// @Param user body models.User true "유저 정보"
// @Success 201 {object} models.User
// @Failure 400 {string} string "Bad Request"
// @Router /users [post]

---

✅ 마무리

Swagger를 활용하면 API 문서를 수동으로 작성할 필요 없이 주석 기반으로 자동화할 수 있습니다.
관리자 페이지에서 API를 테스트할 수도 있고, 프론트엔드와의 협업 효율도 높아집니다.
다음 글에서는 실제 Admin Dashboard 프론트엔드와 이 API를 React + Tailwind로 연동하는 과정을 다루겠습니다.

---

 

GoSwagger, GolangSwagger적용, RESTAPI문서화, SwaggerUI, API자동문서화, GoOpenAPI, Go백엔드문서, SwaggerGo예제, API협업툴, AdminDashboardAPI문서