Go와 Gin Framework 를 사용한 게시판 만들기 (2) - Swagger 붙이기

이번에는 Go에서 Swagger를 통해 API명세를 진행해 보겠다.
Go는 자바에 비해 좀 귀찮다.

세팅하기

먼저 Terminal상에서 Swagger에 필요한 세팅을 받아줄 것이다.

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

그러면 이렇게 알아서 관련된 것들을 module에 추가해준다.

swagger가 제대로 설치되었는지 확인하기 위해 한번 관련 명령어를 쳐본다.

swag

이거 만약에 쳐봤는데 안나오면 아마 PATH가 제대로 설정되지 않았을 확률이 높다.

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

이거 해보셈..

이제 gin Framework에 맞춰서 여기 필요한 gin swagger를 받아준다.

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

적용하기

• main.go 파일

import (
    controller "ryoochanishandsome/controller"

    "ryoochanishandsome/docs"

    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

// @title Swagger Example API
// @version 1.0
// @description This is ryooochan personal project
// @termsOfService http://swagger.io/terms/

// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /api/v1
func main() {
    r := gin.Default()

    docs.SwaggerInfo.Title = "Swagger Example API"

    // localhost:8080/docs/index.html 으로 swagger 확인하기
    r.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    v1Api := r.Group("/api/v1")
    {
        v1Api.GET("/testGet", controller.ControllerTest)
    }

    r.Run("localhost:8080")
}

저기서 나머지는 괜찮은데 docs를 가져오는건 직접 적어준는걸 추천한다.
{자기프로젝트모듈명}/docs 이다.

Go에서 Swagger은 주석을 사용하여 내용을 표현한다.
Swagger에서 내용을 표현하거나 변수를 사용하거나 Path를 설정하는 모든 부분에서 주석을 사용한다는 것이다.

이부분은 주석을 잘 확인해 주면 될것이다.

• controller.go 파일

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

/* 아래 항목이 swagger에 의해 문서화 된다. */
// @Summary Swagger 설정 테스트...
// @Description Swagger 설정 되었는지, API통신 가능한지 Test중
// @name testGet
// @Router /testGet [get]
// @Success 200 {string} {string} ok, 잘 됩니다.
// @Failure 400
func ControllerTest(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{
        "status": "ok",
        "data":   "잘 됩니다.",
    })
}

• swagger init하기

이제 swagger정보를 만들어 줄 것이다.
Go 터미널에서(main.go)가 있는 위치에서 진행해준다.

swag init

을 하면

요렇게 나오고 swagger.json, swagger.yml, docs.go 파일들이 docs파일 아래에 생긴걸 확인 가능하다.
이걸 보면 아까 main.go에서 적용한 docs는 여기서 가져온다는것을 알 수 있다.

이제 한번 서버를 실행해 보자, debug해준 뒤에

http://localhost:8080/docs/index.html

여기 접속한다.

이런 화면을 볼 수 있다.

한번 테스트해 보면

잘 나온다.