GoLang + Swagger — swaggo로 API 문서 자동 생성하기

최초 작성: 2021년 03월 15일 · 최종 갱신: 2026년 07월 15일 구버전 go get 설치 방식을 go install 기준으로 갱신하고, 더 이상 필요 없는 의존성을 정리했다.

API 만드는 프로젝트에 Swagger 를 붙여보자

GoLang 에서는 swaggo 를 활용해서 붙일 수 있다.

---

Step1. Install

swag CLI 는 전역 도구라 go install 로 설치하고, http-swagger 는 프로젝트 의존성이라 go get 으로 추가한다.

Code
go install github.com/swaggo/swag/cmd/swag@latest
go get -u github.com/swaggo/http-swagger

swag - Swagger 2.0 의 Go annotations 활용 http-swagger - Swagger UI 를 doc 으로 만들어 줌

구버전에서는 go get -u github.com/swaggo/swag/cmd/swag 으로 CLI 를 설치했지만, Go 1.17 부터 바이너리 설치는 go install 로 바뀌었다. 당시 함께 설치하던 github.com/alecthomas/template 은 이제 필요 없다.

Step2. Definition

Code
type test struct {
    A int
    B string
}

// @title onlyOurs API
// @version 0.0.1
// @description This is onlyOurs API
// @host localhost:9999
// @BasePath /
func main() {
    router := mux.NewRouter()

    router.HandleFunc("/", func(w http.ResponseWriter, rq *http.Request) {
        core.WriteJSON(w, test {
            5,
            "test",
        })
    })

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

    http.ListenAndServe(":9999", router)
}

내가 사용한 샘플 코드이다. router.PathPrefix("/swagger").Handler(httpSwagger.WrapHandler) 로 라우팅해주고, Annotation 들로 설명 적기

Step3. Docs Create

Code
swag init -g main.go

도큐먼트들을 만들어 준다. Main 파일로 Init 하면 프로젝트에 docs 디렉토리가 생성된다.

Step4. Import

Code
import (
    _ "{프로젝트명}/docs" // docs is generated by Swag CLI, you have to import it.
    httpSwagger "github.com/swaggo/http-swagger"
)

httpSwagger 는 Step2 작업으로 임포트 됐을거고, _ 부분을 따로 임포트 해주어야 한다 ! 본인의 프로젝트 뒤에 docs 를 해주면 된다.

위 작업까지 해주고 실행해주면 아래처럼 이쁜 초기 세팅된 Swagger UI 두둥등장

이후 API 나 어노테이션을 수정했다면 swag init -g main.go 를 다시 실행해서 문서를 갱신해주면 된다.

구몬이 되어준 링크 쇽쇽