doc: update swagger

gsxhnd · Jul 29, 2024 · cee97b1 · cee97b1
1 parent a5e9888
commit cee97b1
Show file tree

Hide file tree

Showing 5 changed files with 82 additions and 12 deletions.
diff --git a/api/handler/log.go b/api/handler/log.go
@@ -27,10 +27,14 @@ func NewLogHandler(v *validator.Validate, l utils.Logger, svc service.LogService
 	}
 }
 
-// @Description  Get Log Info from database by log id
+// @Summary      Log Data Info
+// @Description  Use log id get log data info
+// @Tags         log
+// @Param        log_id    path     string  true  "search by log id"
 // @Produce      json
 // @Success      200
-// @Router       /log/:log_id [get]
+// @Router       /api/v1/log/:log_id [get]
+// @Success 200 {object} model.Log
 func (h *logHandler) GetLogInfoByLogId(ctx *fiber.Ctx) error {
 	var logId = ctx.Params("log_id")
 	err := h.validator.Var(logId, "gt=10")
@@ -46,10 +50,14 @@ func (h *logHandler) GetLogInfoByLogId(ctx *fiber.Ctx) error {
 	return ctx.Status(200).JSON(data)
 }
 
+// @Summary      List Log Data
 // @Description  Get Log Info List from database
+// @Tags         log
+// @Param        pagination    query     model.Pagination  false  "name search by q"  Format(email)
 // @Produce      json
 // @Success      200
-// @Router       /log [get]
+// @Router       /api/v1/log [get]
+// @Success 200 {array} model.Log
 func (h *logHandler) GetLogInfoList(ctx *fiber.Ctx) error {
 	var p = model.Pagination{}
 	if err := ctx.QueryParser(&p); err != nil {

diff --git a/api/router/init.go b/api/router/init.go
@@ -24,7 +24,6 @@ type router struct {
 // @license.name  MIT
 // @license.url   https://opensource.org/license/mit
 // @host      localhost:8080
-// @BasePath  /api/v1
 // @securityDefinitions.basic  BasicAuth
 // @externalDocs.description  OpenAPI
 func NewRouter(cfg *utils.Config, m middleware.Middlewarer, h handler.Handler) (Router, error) {
@@ -44,9 +43,9 @@ func NewRouter(cfg *utils.Config, m middleware.Middlewarer, h handler.Handler) (
 
 func (r *router) Run() error {
 	r.app.Use(r.m.RequestLog)
+	r.app.Get("/ping", r.h.PingHandler.Ping)
 
 	api := r.app.Group("/api/v1")
-	api.Get("/ping", r.h.PingHandler.Ping)
 	api.Get("/log", r.h.LogHandler.GetLogInfoList)
 	api.Get("/log/:log_id", r.h.LogHandler.GetLogInfoByLogId)
 	// api.Get("/paifu")

diff --git a/docs/swagger.yaml b/docs/swagger.yaml
@@ -1,4 +1,20 @@
-basePath: /api/v1
+definitions:
+  model.Log:
+    description: Log Data info
+    properties:
+      game_date:
+        description: game start date
+        type: string
+      game_type:
+        description: game type
+        type: string
+      id:
+        description: id
+        type: integer
+      log_id:
+        description: log id
+        type: string
+    type: object
 externalDocs:
   description: OpenAPI
 host: localhost:8080
@@ -11,6 +27,49 @@ info:
   title: Tenhou API
   version: "1"
 paths:
+  /api/v1/log:
+    get:
+      description: Get Log Info List from database
+      parameters:
+      - description: Offset
+        in: query
+        name: offset
+        type: integer
+      - description: Page size
+        in: query
+        name: page_size
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            items:
+              $ref: '#/definitions/model.Log'
+            type: array
+      summary: List Log Data
+      tags:
+      - log
+  /api/v1/log/:log_id:
+    get:
+      description: Use log id get log data info
+      parameters:
+      - description: search by log id
+        in: path
+        name: log_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/model.Log'
+      summary: Log Data Info
+      tags:
+      - log
   /ping:
     get:
       description: ping serivce working, db connect

diff --git a/model/log.go b/model/log.go
@@ -2,9 +2,11 @@ package model
 
 import "time"
 
+// Log Data info
+// @Description Log Data info
 type Log struct {
-	Id       uint      `json:"id"`
-	LogId    string    `json:"log_id"`
-	GameType string    `json:"game_type"`
-	GameDate time.Time `json:"game_date"`
+	Id       uint      `json:"id"`        //id
+	LogId    string    `json:"log_id"`    // log id
+	GameType string    `json:"game_type"` // game type
+	GameDate time.Time `json:"game_date"` // game start date
 }
diff --git a/model/pagination.go b/model/pagination.go
@@ -1,6 +1,8 @@
 package model
 
+// Pagination
+// @Description Pagination
 type Pagination struct {
-	PageSize uint `query:"page_size"`
-	Offset   uint `query:"offset"`
+	PageSize uint `json:"page_size" query:"page_size"` // Page size
+	Offset   uint `json:"offset" query:"offset"`       // Offset
 }