API 서버를 작성하면서 swagger 사용법을 간단하게 정리해보고자 한다

Swagger?

Go 언어로 API 서버를 작성 시 API 정보를 소스코드와 함께 주석으로 관리하면 문서를 생성해주는 라이브러리이다.

다양한 웹 프레임워크가 있는 Go 언어답게 이 라이브러리도 다양한 프레임워크를 지원한다.

Github 링크: https://github.com/swaggo/swag

여기서 Fiber 웹 프레임워크를 이용해서 작성하고 있으며 이에 대한 설정 방법도 저장소에 잘 나와있다.

Github 링크: https://github.com/gofiber/swagger

초기 설정

swagger는 소스코드를 대상으로 문서 표현을 위한 json 파일을 생성한다.

그러므로 이를 수행할 커맨드라인 프로그램을 우선 설치해준다.

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

정상적인 설치를 확인하기 위해서는 swag 명령을 입력해보자.

만약 명령어를 찾을 수 없다면 GOPATH 환경변수 밑에 bin 경로를 PATH 환경변수에 등록하여야 한다.

우선 간단하게 동작을 잘하는지 확인하기 위해서 main 메소드와 API 메소드 하나에 간단하게 필수 조건 정도를 샘플로 주석을 달아주었다.

main.go

//	@title		API Doc
//	@version	1.0
func main() {
	...
}

서비스 파일

package v1

import "github.com/gofiber/fiber/v2"

type PingResponse struct {
	Msg string `json:"msg"`
}

// PingService godoc
//
//	@summary		Send ping
//	@description	Pong!을 응답받습니다.
//	@accept			json
//	@param			Authorization	header		string	false	"인증 키"
//	@success		200	{object}	v1.PingResponse
//	@router			/api/v1/ping [get]
func PingService(c *fiber.Ctx) error {
	c.JSON(PingResponse{
		Msg: "Pong!",
	})

	return nil
}

이후 아래 명령어를 통해서 swagger 주석을 정렬해주는 것을 권장한다.

swag fmt

이후 문서를 생성한다.

swag init

생성 중 오류가 발생하면 로그상에 친절하게 알려주며, 성공 시 프로젝트 폴더 하위에 doc 경로를 생성하고 관련 파일을 추가해준다.

이제는 문서를 확인해봐야할 차례이다.

문서를 fiber 웹에서 미들웨어를 통해 제공하기 위하여 아래 패키지를 추가한다.

go get -u github.com/gofiber/swagger

이후 문서를 볼 수 있도록 라우팅을 추가해야 하는데.

우선 관련한 패키지 import 부터 한다.

"github.com/gofiber/swagger"
_ "모듈명/docs"

swagger의 fiber용 패키지와 swag init 명령어로 생성된 docs를 import 한다.

app.Get("/라우팅경로/*", swagger.HandlerDefault)

위와 같이 라우팅을 해주면 완료.

이후 웹 페이지에 들어가면 다음과 같이 깔끔하게 API 문서가 생성되어 있다.

API 문서 테스트도 진행해볼 수 있다.