GitHub - swaggo/swag: Automatically generate RESTful API documentation with Swagger 2.0 for Go.
go get -u github.com/swaggo/swag/cmd/swag
## go 1.17 이상
go install github.com/swaggo/swag/cmd/swag@latest
## 설치 경로 확인
GOPATH/bin
## 사용 시
swag init
// gin 프레임워크에서 사용하는 swagger 미들웨어 패키지
go get -u github.com/swaggo/gin-swagger
// swagger embed files
go get -u github.com/swaggo/files
e := gin.Default()
e.Use(gin.Logger())
e.Use(gin.Recovery())
e.Use(CORS())
e.GET("/health")
//swagger 핸들러 미들웨어에 등록
e.GET("/swagger/:any", ginSwg.WrapHandler(swgFiles.Handler))
docs.SwaggerInfo.Host = "localhost" //swagger 정보 등록
account := e.Group("acc/v01", liteAuth())
{
account.GET("/ok", p.ct.GetOK)
}
@Summary
: 해당 API에 대한 간단 요약@Description
: 해당 기능에 대한 설명@name
: API 이름@Accept
: API 입력 형태(txt, json, etc...)@Produce
: API 출력 형태(txt, json, etc...)@Param
: API 사용 파라메터 및 타입@Router
: URI 정보 및 [메소드]@Success
: 응답코드 및 응답 객체// GetOK godoc
// @Summary call GetOK, return ok by json.
// @Description api test를 위한 기능.
// @name GetOK
// @Accept json
// @Produce json
// @Param name path string true "User name"
// @Router /acc/v01/ok [get]
// @Success 200 {object} Controller
func (p *Controller) GetOK(c *gin.Context) {
c.JSON(200, gin.H{"msg": "ok"})
return
}
> go run main.go
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
- using env: export GIN_MODE=release
- using code: gin.SetMode(gin.ReleaseMode)
[GIN-debug] GET /health --> lecture/go-swag/controller.(*Controller).GetOK-fm (4 handlers)
[GIN-debug] GET /swagger/:any --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (4 handlers)
[GIN-debug] GET /acc/v01/ok --> lecture/go-swag/controller.(*Controller).GetOK-fm (5 handlers)
@Summary
: 해당 API에 대한 간단 요약@Router
: URI 정보 및 [메소드]// GetOK godoc
// @Summary call GetOK, return ok by json.
// @Router /acc/v01/ok [get]
func (p *Controller) GetOK(c *gin.Context) {
c.JSON(200, gin.H{"msg": "ok"})
return
}
@Description
: 해당 기능에 대한 설명// GetOK godoc
// @Summary call GetOK, return ok by json.
// @Description api test를 위한 기능.
// @Router /acc/v01/ok [get]
func (p *Controller) GetOK(c *gin.Context) {
c.JSON(200, gin.H{"msg": "ok"})
return
}
@name
: API 이름// GetOK godoc
// @Summary call GetOK, return ok by json.
// @Description api test를 위한 기능.
// @name GetOK
// @Router /acc/v01/ok [get]
func (p *Controller) GetOK(c *gin.Context) {
c.JSON(200, gin.H{"msg": "ok"})
return
}
@Accept
: API 입력 형태(txt, json, etc...)// GetOK godoc
// @Summary call GetOK, return ok by json.
// @Accept json
// @Router /acc/v01/ok [get]
func (p *Controller) GetOK(c *gin.Context) {
c.JSON(200, gin.H{"msg": "ok"})
return
}
@Produce
: API 출력 형태(txt, json, etc...)// GetOK godoc
// @Summary call GetOK, return ok by json.
// @Description api test를 위한 기능.
// @Produce json
// @Router /acc/v01/ok [get]
func (p *Controller) GetOK(c *gin.Context) {
c.JSON(200, gin.H{"msg": "ok"})
return
}
@Param
: API 사용 파라메터 및 타입@Param [param name] [param type] [data type] [is mandatory] [comment] [attribute(optional)]
// @Param pnum path string true "PNUM"
func (p *Controller) GetOK(c *gin.Context) {
c.JSON(200, gin.H{"msg": "ok"})
return
}
@Success
: 응답코드 및 응답 객체// GetOK godoc
// @Summary call GetOK, return ok by json.
// @Description api test를 위한 기능.
// @Router /acc/v01/ok [get]
// @Success 200 {object} Controller
func (p *Controller) GetOK(c *gin.Context) {
c.JSON(200, gin.H{"msg": "ok"})
return
}