golang gin API + swagger 적용하기

swagger 는 단순 API 문서화를 넘어 FE와 연동에도 적극적으로 활용된다. 그렇기 때문에 API Server의 swagger 연동은 당연하게 필요하게 되는데, 간단한 go API server에 swaggo를 적용해보자

swaggo?

Automatically generate RESTful API documentation with Swagger 2.0 for Go

위 설명에 나와있듯이 자동으로 REST API docs를 만들어주는 프레임웍을 의미한다.

방법

swaggo module 다운로드

아래처럼 설치 후 Go Project root 경로에서 init을 수행한다. 그럼 자동으로 docs/ directory와 필요 파일들을 생성된다.

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

gin-swagger 다운로드

이후 gin API 와 연동을 위해 아래 모듈을 다운로드한다.

$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files

코드작성

코드는 지난 포스트에서 사용한 것을 그대로 활용할 것이다.

package main

import (
    "github.com/gin-gonic/gin"
    _ "{Project_ROOT_PATH}/docs"
)

// @BasePath /v1

// swagger API 선언
func setupSwagger(r *gin.Engine) {
    r.GET("/", func(c *gin.Context) {
        c.Redirect(http.StatusFound, "/swagger/index.html")
    })

    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

// requestPing
// @Summary This is simple Summary.
// @Description This is detail Description.
// @Accept  json
// @Produce  json
// @Router /v1/ping [get]
// @Success 200 {object} string
func requestPing(c *gin.Context) {
    fmt.Println("got ping")
    c.JSON(200, gin.H{
        "message": "pong",
    })
}

func main() {
  // router 초기화
  r := gin.Default()  
  // middleware 설정
  setupSwagger(r)
  // handler 설정
  r.GET("/ping", requestPing)  
  // apiserver 실행
  r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080")  
}

중요한 몇가지 포인트가 있는데,

• _ "{Project_ROOT_PATH}/docs" 프로젝트 루트 패스에 docs 패키지를 import 한다.
• // @BasePath /v1 BasePath 를 선언한다
• requestPing 하위 주석들을 통해 API의 스펙을 기술한다. ( 자세한 내용은 구글께.. )
• setupSwagger 를 통해 / path 로 들어온 요청을 /swagger/index.html 으로 redirect 하고 swagger 를 노출한다.

결과

위 코드 그대로 실행해서 http://localhost:8080/ 또는 http://localhost:8080/swagger/index.html 으로 접속하면 아래 화면을 확인할 수 있다.