Refine proto and swag (#281)

Signed-off-by: wayblink <[email protected]>
zilliztech · Jan 10, 2024 · 7845b38 · 7845b38
1 parent 05424bc
commit 7845b38
Show file tree

Hide file tree

Showing 9 changed files with 96 additions and 47 deletions.
diff --git a/build.sh b/build.sh
@@ -1,4 +1,4 @@
 go get
+./gen_proto.sh
+./gen_swag.sh
 go build
-./proto_gen_go.sh
-swag init
diff --git a/core/backup_server.go b/core/backup_server.go
@@ -132,7 +132,7 @@ func wrapHandler(handle handlerFunc) gin.HandlerFunc {
 // @Tags Backup
 // @Accept application/json
 // @Produce application/json
-// @Param request_id header string true "request_id"
+// @Param request_id header string false "request_id"
 // @Param object body backuppb.CreateBackupRequest   true  "CreateBackupRequest JSON"
 // @Success 200 {object} backuppb.BackupInfoResponse
 // @Router /create [post]
@@ -156,7 +156,7 @@ func (h *Handlers) handleCreateBackup(c *gin.Context) (interface{}, error) {
 // @Description List all backups in current storage
 // @Tags Backup
 // @Produce application/json
-// @Param request_id header string true "request_id"
+// @Param request_id header string false "request_id"
 // @Param collection_name query string true "collection_name"
 // @Success 200 {object} backuppb.ListBackupsResponse
 // @Router /list [get]
@@ -178,7 +178,7 @@ func (h *Handlers) handleListBackups(c *gin.Context) (interface{}, error) {
 // @Description Get the backup with the given name or id
 // @Tags Backup
 // @Produce application/json
-// @Param request_id header string true "request_id"
+// @Param request_id header string false "request_id"
 // @Param backup_name query string true "backup_name"
 // @Param backup_id query string true "backup_id"
 // @Success 200 {object} backuppb.BackupInfoResponse
@@ -202,7 +202,7 @@ func (h *Handlers) handleGetBackup(c *gin.Context) (interface{}, error) {
 // @Description Delete a backup with the given name
 // @Tags Backup
 // @Produce application/json
-// @Param request_id header string true "request_id"
+// @Param request_id header string false "request_id"
 // @Param backup_name query string true "backup_name"
 // @Success 200 {object} backuppb.DeleteBackupResponse
 // @Router /delete [delete]
@@ -222,7 +222,7 @@ func (h *Handlers) handleDeleteBackup(c *gin.Context) (interface{}, error) {
 // @Tags Restore
 // @Accept application/json
 // @Produce application/json
-// @Param request_id header string true "request_id"
+// @Param request_id header string false "request_id"
 // @Param object body backuppb.RestoreBackupRequest   true  "RestoreBackupRequest JSON"
 // @Success 200 {object} backuppb.RestoreBackupResponse
 // @Router /restore [post]
@@ -251,7 +251,7 @@ func (h *Handlers) handleRestoreBackup(c *gin.Context) (interface{}, error) {
 // @Description Get restore task state with the given id
 // @Tags Restore
 // @Produce application/json
-// @Param request_id header string true "request_id"
+// @Param request_id header string false "request_id"
 // @param id query string true "id"
 // @Success 200 {object} backuppb.RestoreBackupResponse
 // @Router /get_restore [get]

diff --git a/core/proto/backup.proto b/core/proto/backup.proto
@@ -1,7 +1,7 @@
 syntax = "proto3";
 package milvus.proto.backup;
 
-import "google/protobuf/struct.proto";
+import "google/protobuf/struct.proto"; // proto define
 
 option go_package="github.com/zilliztech/milvus-backup/core/proto/backuppb";
 
@@ -253,17 +253,17 @@ message RestoreBackupRequest {
   string path = 8;
   // database and collections to restore. A json string. To support database. 2023.7.7
   google.protobuf.Value db_collections = 9;
-  // if true only restore meta
+  // if true only restore meta, not restore data
   bool metaOnly = 10;
   // if true restore index info
   bool restoreIndex = 11;
   // if true use autoindex when restore vector index
   bool useAutoIndex = 12;
-  // if true drop the collections
+  // if true, drop existing target collection before create
   bool dropExistCollection = 13;
-  // if true drop index info
+  // if true, drop existing index of target collection before create
   bool dropExistIndex = 14;
-  // if true will skip create collections
+  // if true, will skip collection, use when collection exist, restore index or data
   bool skipCreateCollection = 15;
 }
 

diff --git a/core/proto/backuppb/backup.pb.go b/core/proto/backuppb/backup.pb.go
diff --git a/docs/docs.go b/docs/docs.go
@@ -233,8 +233,7 @@ const docTemplate = `{
                         "type": "string",
                         "description": "request_id",
                         "name": "request_id",
-                        "in": "header",
-                        "required": true
+                        "in": "header"
                     },
                     {
                         "description": "RestoreBackupRequest JSON",
@@ -791,15 +790,15 @@ const docTemplate = `{
                     "type": "string"
                 },
                 "dropExistCollection": {
-                    "description": "if true drop the collections",
+                    "description": "if true, drop existing target collection before create",
                     "type": "boolean"
                 },
                 "dropExistIndex": {
-                    "description": "if true drop index info",
+                    "description": "if true, drop existing index of target collection before create",
                     "type": "boolean"
                 },
                 "metaOnly": {
-                    "description": "if true only restore meta",
+                    "description": "if true only restore meta, not restore data",
                     "type": "boolean"
                 },
                 "path": {
@@ -815,7 +814,7 @@ const docTemplate = `{
                     "type": "boolean"
                 },
                 "skipCreateCollection": {
-                    "description": "if true will skip create collections",
+                    "description": "if true, will skip collection, use when collection exist, restore index or data",
                     "type": "boolean"
                 },
                 "useAutoIndex": {

diff --git a/docs/swagger.json b/docs/swagger.json
@@ -225,8 +225,7 @@
                         "type": "string",
                         "description": "request_id",
                         "name": "request_id",
-                        "in": "header",
-                        "required": true
+                        "in": "header"
                     },
                     {
                         "description": "RestoreBackupRequest JSON",
@@ -783,15 +782,15 @@
                     "type": "string"
                 },
                 "dropExistCollection": {
-                    "description": "if true drop the collections",
+                    "description": "if true, drop existing target collection before create",
                     "type": "boolean"
                 },
                 "dropExistIndex": {
-                    "description": "if true drop index info",
+                    "description": "if true, drop existing index of target collection before create",
                     "type": "boolean"
                 },
                 "metaOnly": {
-                    "description": "if true only restore meta",
+                    "description": "if true only restore meta, not restore data",
                     "type": "boolean"
                 },
                 "path": {
@@ -807,7 +806,7 @@
                     "type": "boolean"
                 },
                 "skipCreateCollection": {
-                    "description": "if true will skip create collections",
+                    "description": "if true, will skip collection, use when collection exist, restore index or data",
                     "type": "boolean"
                 },
                 "useAutoIndex": {

diff --git a/docs/swagger.yaml b/docs/swagger.yaml
@@ -382,13 +382,13 @@ definitions:
           database. 2023.7.7
         type: string
       dropExistCollection:
-        description: if true drop the collections
+        description: if true, drop existing target collection before create
         type: boolean
       dropExistIndex:
-        description: if true drop index info
+        description: if true, drop existing index of target collection before create
         type: boolean
       metaOnly:
-        description: if true only restore meta
+        description: if true only restore meta, not restore data
         type: boolean
       path:
         description: if bucket_name and path is set. will override bucket/path in
@@ -401,7 +401,8 @@ definitions:
         description: if true restore index info
         type: boolean
       skipCreateCollection:
-        description: if true will skip create collections
+        description: if true, will skip collection, use when collection exist, restore
+          index or data
         type: boolean
       useAutoIndex:
         description: if true use autoindex when restore vector index
@@ -709,7 +710,6 @@ paths:
       - description: request_id
         in: header
         name: request_id
-        required: true
         type: string
       - description: RestoreBackupRequest JSON
         in: body

diff --git a/proto_gen_go.sh → gen_proto.sh b/proto_gen_go.sh → gen_proto.sh