go fiber에 swagger를 붙여보자.

Swagger는 API 문서화 도구로, API의 구조와 사용 방법을 사용자에게 시각적으로 보여주어 API 테스트 및 통합을 쉽게하게 해준다. 이 번 포스팅에서는 간단하게 Go Fiber와 Swagger를 어떻게 통합하여 API 문서를 자동으로 생성하고 제공하는지 알아보자.

 

코드는 https://github.com/ggorockee/camping-backend-with-go.git   여기에 있다.

GitHub - ggorockee/camping-backend-with-go

 

당연한 얘기겠지만 설치부터 시작해야 한다.

$ go get -u github.com/swaggo/swag/cmd/swag
$ go get "github.com/gofiber/contrib/swagger"

 

package main

import (
	...
	"github.com/gofiber/contrib/swagger"
	"github.com/gofiber/fiber/v2"
)

func main() {
	...

	// swagger settings
	swaggerCfg := swagger.Config{
		BasePath: "/v1",
		FilePath: "./docs/swagger.yaml",
		Path:     "docs",
	}
	app.Use(swagger.New(swaggerCfg))

	...
}

 

다른 여러가지 방법이 있지만 나는 middleware를 이용해서 swagger를 붙이기로 했다. swagger인스턴스를 초기화하여 fiber app에 middleware를 이용해서 붙였다.

그리고 우리는 gorm을 사용하기 때문에 main.go가 있는 파일 위치에서

$ swag init --parseDependency

위 명령어를 실행해준다. 그리고 나면

이렇게 docs라는 폴더가 만들어지는데 이 파일을 참조하도록 main.go에서 세팅해준것이다.

그리고 나서

$go run main.go

로 실행한 후에

http://localhost:3000/v1/docs로 접속하면

이런 화면이 뜰 것이다. 이 화면이 보이면 swagger를 붙이는 거에는 성공한거다. 이제 우리의 라우터를 swagger에 등록해주자.

 

Swagger에서 Error와 Success에 적절한 응답을 보내기 위해서는 structure로 명시되어 있어야 하는데 우리가 만든 routes/user.go에는

func UserErrorResponse(err error) *fiber.Map {
	return &fiber.Map{
		"status": false,
		"data":   "",
		"error":  err.Error(),
	}
}

func UserSuccessResponse(data *entities.User) *fiber.Map {
	user := User{
		Id:       data.Id,
		Email:    data.Email,
		Username: data.Username,
	}
	return &fiber.Map{
		"status": true,
		"data":   user,
		"error":  nil,
	}
}

 

type이 아니고 func로 선언되어 있다. 이를 해결해주기 위해

이 부분을

type JsonResponse struct {
	Status bool   `json:"status"`
	Data   any    `json:"data"`
	Error  string `json:"error"`
}

func UserErrorResponse(err error) *JsonResponse {

	return &JsonResponse{
		Status: false,
		Data:   nil,
		Error:  err.Error(),
	}
}

func UserSuccessResponse(data *entities.User) *JsonResponse {
	user := User{
		Id:       data.Id,
		Email:    data.Email,
		Username: data.Username,
	}
	return &JsonResponse{
		Status: true,
		Data:   user,
		Error:  "",
	}
}

 

JsonResponse를 외부로 빼자. 앞으로 이 response는 계속 쓸것 같다. presenter/response.go 라는 파일을 만들어서 새로 작성했다.

이렇게 바꾸었다. 이러면 기존 동작에는 무리가 없고 swagger에는 JsonReponse를 이용해서 붙일 수가 있다.

 

이제 handlers/user_handler.go파일을 다음과 같이 추가하자.

// CreateUser is a function to create user data to database
// @Summary Create User
// @Description Create User
// @Tags Users
// @Accept json
// @Produce json
// @Param user body entities.User true "Register user"
// @Success 200 {object} presenter.JsonResponse{data=presenter.User}
// @Failure 503 {object} presenter.JsonResponse
// @Router /user [post]
func CreateUser(service user.Service) fiber.Handler {
	// Some Logic
}

 

이렇게 주석과 Tag형태로 swagger에 등록해주면 된다.

그리고

$ swag init --parseDependency
$ go run main.go

 

 

 

성공적으로 swagger에 등록한 것을 볼 수 있다. 만약 이 화면이 나오지 않으면 캐시를 지우고해보자. 그러면 나올 수도 있다. 나는 캐시가 안지웠어서 내가 잘못한줄 알았는데 캐시를 지우니까 되더라..