[feat]: add swagger doc

Makefile

@@ -20,6 +20,7 @@ endif
 init:
 	go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
 	go install github.com/google/wire/cmd/wire@latest
+	go install github.com/swaggo/swag/cmd/swag@latest
 
 .PHONY: config
 # generate internal proto
@@ -52,6 +53,10 @@ all:
 run: all build
 	./bin/demo
 
+.PHONY: swag
+swag:
+	swag init -g ./internal/router/web.go --output ./docs/
+
 # show help
 help:
 	@echo ''

go.mod

@@ -19,11 +19,21 @@ require (
 	github.com/gin-gonic/gin v1.8.2
 	github.com/google/uuid v1.3.0
 	github.com/shopspring/decimal v1.3.1
+	github.com/swaggo/files v0.0.0-20220728132757-551d4a08d97a
+	github.com/swaggo/gin-swagger v1.5.3
+	github.com/swaggo/swag v1.8.1
 )
 
 require (
+	github.com/KyleBanks/depth v1.2.1 // indirect
+	github.com/PuerkitoBio/purell v1.1.1 // indirect
+	github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
 	github.com/fsnotify/fsnotify v1.5.4 // indirect
 	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/go-openapi/jsonpointer v0.19.5 // indirect
+	github.com/go-openapi/jsonreference v0.19.6 // indirect
+	github.com/go-openapi/spec v0.20.4 // indirect
+	github.com/go-openapi/swag v0.19.15 // indirect
 	github.com/go-playground/form/v4 v4.2.0 // indirect
 	github.com/go-playground/locales v0.14.0 // indirect
 	github.com/go-playground/universal-translator v0.18.0 // indirect
@@ -36,8 +46,10 @@ require (
 	github.com/imdario/mergo v0.3.12 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/leodido/go-urn v1.2.1 // indirect
+	github.com/mailru/easyjson v0.7.6 // indirect
 	github.com/mattn/go-isatty v0.0.16 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect

internal/biz/biz.go

@@ -4,3 +4,10 @@ import "github.com/google/wire"
 
 // ProviderSet is biz providers.
 var ProviderSet = wire.NewSet(NewReportUsecase)
+
+type Response struct {
+	RequestId string      `json:"request_id"`
+	Code      string      `json:"code"`
+	Msg       string      `json:"msg"`
+	Data      interface{} `json:"data"`
+}

internal/router/web.go

@@ -6,6 +6,10 @@ import (
 	"github.com/gin-contrib/pprof"
 	"github.com/gin-gonic/gin"
 
+	"github.com/swaggo/files"
+	"github.com/swaggo/gin-swagger"
+
+	_ "demo/docs"
 	"demo/internal/router/mid"
 	"demo/internal/service"
 )
@@ -17,17 +21,29 @@ type Web struct {
 	Report  *service.ReportService
 }
 
+// RouterInit
+// @title Ads Api Docs
+// @version 1.0
+// @description swagger api for [ads](https://test.adsdesk.cn/)
+// @host 127.0.0.1:8000
+// @BasePath /api/v1
+// @securityDefinitions.apikey ApiKeyAuth
+// @in header
+// @name token
 func (p *Web) RouterInit(engine *gin.Engine) {
 	engine.Use(p.Common.SetRequestId, p.Common.PassMethods)
 	engine.NoRoute(func(c *gin.Context) {
 		c.JSON(http.StatusNotFound, gin.H{"code": "404", "message": "PageNo not found"})
 	})
+	if gin.Mode() != gin.ReleaseMode {
+		engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+	}
 	// add pprof to look at the heap,a 30-second CPU and so on profile
 	// eg: go tool pprof http://localhost:8000/api/pprof/profile
 	pprof.Register(engine, "/api/pprof")
 	// add api
 	engine.GET("/hello/:name", p.Greeter.SayHello)
-	api := engine.Group("/api", p.Jwt.CheckToken)
+	api := engine.Group("/api/v1", p.Jwt.CheckToken)
 	{
 		report := api.Group("/report")
 		{

internal/service/report.go

@@ -22,6 +22,14 @@ func NewReportService(uc *biz.ReportUsecase, logger log.Logger) *ReportService {
 }
 
 // ListCampaignData 查询广告组数据报表
+// @tags report
+// @Summary 查询广告组数据报表
+// @Description 查询广告组数据报表
+// @Accept json
+// @Produce  json
+// @Param req body biz.ListReportRequest true "请求参数"
+// @Success 200 {object} biz.Response{data=biz.ListCampaignResponse} "success"
+// @Router /report/campaign [POST]
 func (p *ReportService) ListCampaignData(ctx *gin.Context) {
 	var req biz.ListReportRequest
 	if err := ctx.ShouldBind(&req); err != nil {
@@ -52,6 +60,14 @@ func (p *ReportService) ListCampaignData(ctx *gin.Context) {
 }
 
 // ListAdData 查询广告计划数据报表
+// @tags report
+// @Summary 查询广告计划数据报表
+// @Description 查询广告计划数据报表
+// @Accept json
+// @Produce  json
+// @Param req body biz.ListReportRequest true "请求参数"
+// @Success 200 {object} biz.Response{data=biz.ListAdResponse} "success"
+// @Router /report/ad [POST]
 func (p *ReportService) ListAdData(ctx *gin.Context) {
 	var req biz.ListReportRequest
 	if err := ctx.ShouldBind(&req); err != nil {
@@ -82,6 +98,14 @@ func (p *ReportService) ListAdData(ctx *gin.Context) {
 }
 
 // ListCreativeData 查询广告创意数据报表
+// @tags report
+// @Summary 查询广告创意数据报表
+// @Description 查询广告创意数据报表
+// @Accept json
+// @Produce  json
+// @Param req body biz.ListReportRequest true "请求参数"
+// @Success 200 {object} biz.Response{data=biz.ListCreativeResponse} "success"
+// @Router /report/creative [POST]
 func (p *ReportService) ListCreativeData(ctx *gin.Context) {
 	var req biz.ListReportRequest
 	if err := ctx.ShouldBind(&req); err != nil {