[Go] Echo에 Swagger 적용하기

nzero·2024년 2월 2일

Where is the Book

목록 보기

3/6

시작하기 전

GOPATH가 환경변수에 추가되어 있는지 확인한다. 없다면 아래와 같이 추가.

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

패키지 설치

API 문서를 자동으로 생성해주는 swag와 echo에서 Middleware로 동작하는 echo-swagger 패키지를 설치한다.

$ go install github.com/swaggo/swag/cmd/swag@latest
$ go get -u github.com/swaggo/echo-swagger

설정

swaggo 페이지에 상세히 설명되어 있다. 프레임워크별로도 확인 가능하며, echo에 대한 내용은 이 페이지에. 그래도 조금 적어보자면

init

init 명령어를 실행하면 docs/docs.go가 생성되는 걸 확인할 수 있다.
swagger에 대한 설정을 변경했을 시, 꼭 init 명령어를 실행해줘야 한다는 사실을 잊지 말자.

swag init

만약 main.go가 아닌 다른 파일에 swagger를 설정했다면, 아래와 같이 해당 경로를 지정해주어야 한다.

swag init -g router/router.go

import 및 middleware 설정

주의할 점! 처음 swagger를 import하면 example docs가 import 되어있는데, 해당 부분을 init 명령어로 생성 된 docs 경로로 변경해줘야 한다. 보통 프로젝트루트/docs에 생성되니 참고하자.

package main

import (
	"github.com/labstack/echo/v4"
	"github.com/swaggo/echo-swagger"

	_ "[project_name]/docs"
)

func main() {
	e := echo.New()

	e.GET("/swagger/*", echoSwagger.WrapHandler)

	e.Logger.Fatal(e.Start(":1323"))
}

사실 swagger는 내용 특성 상 개발망에서만 접근이 가능하도록 설정하는게 좋다. 해당 부분에 대한 내용은 이 포스트에 작성해뒀으니 참고하자.

Swagger 주석 작성

swagger가 문서를 생성할 때는, 선언 된 주석을 참고한다.
사용 가능한 declarative comments는 공식 문서에서 확인 가능.

Main 주석 작성

echo를 생성하는 곳에 설정하는 주석은 swagger UI 페이지에 표기될 내용을 기재할 수 있다.

package main

import (
	...
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.

// @host petstore.swagger.io
// @BasePath /v2
func main() {
	e := echo.New()

	e.GET("/swagger/*", echoSwagger.WrapHandler)

	e.Logger.Fatal(e.Start(":1323"))
}

Handler 주석 작성

각 Handler마다 필요한 내용을 기재하면 된다. 이용자가 작성한 Struct도 아래와 같이 Param 형식으로 설정 가능하다.
Param은 띄어쓰기로 항목을 구별하며, 각 항목은 아래와 같다.

@Param [param name] [param type] [data type] [is mandatory] [comment attribute(optional)]

...
type Search struct {
	SearchQuery string `json:"s"`
}
...
type Book struct {
	Title     string `json:"title"`
	Author    string `json:"author"`
}
...

// @Summery Search Book
// @Accept json
// @Produce json
// @Param s body Search true "Book Name"
// @Success 200 {object} []Book
// @Router /search [post]
func SearchHandler(c echo.Context) error {
	var search Search
	...
	return c.JSON(http.StatusOK, bookList)
}