Go언어로 웹 서버 개발 시 Swagger 문서 자동 생성하기

개요

지금까지 Swagger 문서를 만드는 작업을 수작업으로 해왔는데, API가 갱신될 떄마다 반영하기가 힘들어서 매번 버전이 다른 문제가 있었다. python의 경우 장고를 사용하면 자동으로 Swagger 문서를 생성해주는 기능이 있어서 Go 언어는 없을까 하여 찾아보니 swaggo를 발견하게 되었다.

Swaggo

Swaggo는 주석을 활용하여 코드로 작성된 내용을 Swagger Documentation 2.0으로 변환한다. Go 언어에서 자주 사용되는 여러 웹 프레임워크를 지원하고 있고, 내가 현재 사용 중인 Echo도 역시 지원한다. 여기서는 Echo Framework를 기준으로 설명한다. Swaggo를 사용하기 위해서는 먼저 CLI 도구가 필수적으로 필요하다. 아래 go get 명령을 사용하여 간단히 다운로드 받을 수 있다.

go get -u github.com/swaggo/swag/cmd/swag

대상이 되는 웹 서버에 Swagger 페이지를 제공하기 위해서는 아래와 같이 echo 프레임워크에 라우팅 설정을 추가해야한다.

e := echo.New()
e.GET("/swagger/*", echoSwagger.WrapHandler)

웹 서버를 구동하고 아래 주소로 접속하면 Swagger 페이지를 볼 수 있다.

http://<서버주소>/swagger/index.html

API 문서 만들기

1. 먼저 Swagger 문서의 기본 정보를 표현하기 위해 main.go 파일의 main 함수에 기본 주석을 작성한다.

    // @title Example API
    // @version 0.0.2
    // @description This is a Example api server
   
    // @contact.name Request permission of Example API
    // @contact.url http://www.yonghochoi.com
    // @contact.email yongho1037@gmail.com
   
    // @host localhost
    // @BasePath /api/v1
    func main() {
        ... 생략 ...
    }

2. API에 해당하는 각 핸들러에 Swagger 문서에 나타낼 내용을 주석으로 작성한다.

    // CollectHost godoc
    // @Summary Host information collection.
    // @Description If it already exists, the changeable information is updated, and in the case of a new host, it is created and returned.
    // @Accept  json
    // @Produce  json
    // @Param apiver path string true "API version"
    // @Param project_id path string true "Project ID"
    // @Success 200 {object} base.Response
    // @Failure 400 {object} base.Response
    // @Failure 404 {object} base.Response
    // @Failure 500 {object} base.Response
    // @Router /{apiver}/projects/{project_id}/hosts [post]
    func (o *Handler) CollectHost(c echo.Context) error {
        .. 생략 ...
    }

   • 주석 사용 규칙은 이 링크를 참고

3. 다음 명령을 사용하여 Swagger 페이지를 표시하기 위해 필요한 파일들을 자동으로 생성한다.

    // main.go 파일이 있는 위치로 이동
    swag i

   • -g 옵션을 사용하여 main.go 파일의 위치를 지정할 수도 있다.

   • 명령을 실행하면 main.go 파일 위치에 docs 디렉토리가 생성되고 그 하위에 docs.go, swager.json, swager.yml 파일이 생성된다.

       └─docs          
          ├─docs.go
          ├─swagger.json     
          └─swagger.yaml

4. 웹 서버를 실행시킨 후 아래 주소로 이동하면 Swagger API 문서를 볼 수 있다.

    http://<웹 서버 주소>/swagger/index.html

참고

swaggo/swag

swaggo/echo-swagger