From 811ebfded0839764c8f1cf09e0732a8a7dc1c732 Mon Sep 17 00:00:00 2001 From: Seokho Son Date: Wed, 26 Jun 2024 16:23:19 +0900 Subject: [PATCH] Enhance API docs for spec and image registeration --- src/api/rest/docs/docs.go | 24 ++++++++++++++++-------- src/api/rest/docs/swagger.json | 24 ++++++++++++++++-------- src/api/rest/docs/swagger.yaml | 25 +++++++++++++++++-------- src/api/rest/server/mcir/image.go | 8 ++++---- src/api/rest/server/mcir/spec.go | 6 +++--- 5 files changed, 56 insertions(+), 31 deletions(-) diff --git a/src/api/rest/docs/docs.go b/src/api/rest/docs/docs.go index 62712e19a..557fd007e 100644 --- a/src/api/rest/docs/docs.go +++ b/src/api/rest/docs/docs.go @@ -6069,22 +6069,26 @@ const docTemplate = `{ "operationId": "PostImage", "parameters": [ { + "enum": [ + "registerWithInfo", + "registerWithId" + ], "type": "string", - "description": "registeringMethod (registerWithInfo or registerWithId)", + "description": "registeringMethod", "name": "action", "in": "query", "required": true }, { "type": "string", - "default": "ns01", + "default": "system-purpose-common-ns", "description": "Namespace ID", "name": "nsId", "in": "path", "required": true }, { - "description": "Details for an image object", + "description": "Specify details of a image object (cspImageName, guestOS, description, ...) manually", "name": "imageInfo", "in": "body", "schema": { @@ -6092,7 +6096,7 @@ const docTemplate = `{ } }, { - "description": "name, connectionName and cspImageId", + "description": "Specify name, connectionName and cspImageId to register an image object automatically", "name": "imageId", "in": "body", "schema": { @@ -6872,9 +6876,13 @@ const docTemplate = `{ "operationId": "PostSpec", "parameters": [ { + "enum": [ + "registerWithInfo", + "registerWithCspSpecName" + ], "type": "string", - "description": "registerWithInfo or else", - "name": "registeringMethod", + "description": "registeringMethod", + "name": "action", "in": "query", "required": true }, @@ -6887,7 +6895,7 @@ const docTemplate = `{ "required": true }, { - "description": "Details for an spec object", + "description": "Specify details of a spec object (vCPU, memoryGiB, ...) manually", "name": "specInfo", "in": "body", "schema": { @@ -6895,7 +6903,7 @@ const docTemplate = `{ } }, { - "description": "name, connectionName and cspSpecName", + "description": "Specify name, connectionName and cspSpecName to register a spec object automatically", "name": "specName", "in": "body", "schema": { diff --git a/src/api/rest/docs/swagger.json b/src/api/rest/docs/swagger.json index af0190aa5..0a24fecfb 100644 --- a/src/api/rest/docs/swagger.json +++ b/src/api/rest/docs/swagger.json @@ -6062,22 +6062,26 @@ "operationId": "PostImage", "parameters": [ { + "enum": [ + "registerWithInfo", + "registerWithId" + ], "type": "string", - "description": "registeringMethod (registerWithInfo or registerWithId)", + "description": "registeringMethod", "name": "action", "in": "query", "required": true }, { "type": "string", - "default": "ns01", + "default": "system-purpose-common-ns", "description": "Namespace ID", "name": "nsId", "in": "path", "required": true }, { - "description": "Details for an image object", + "description": "Specify details of a image object (cspImageName, guestOS, description, ...) manually", "name": "imageInfo", "in": "body", "schema": { @@ -6085,7 +6089,7 @@ } }, { - "description": "name, connectionName and cspImageId", + "description": "Specify name, connectionName and cspImageId to register an image object automatically", "name": "imageId", "in": "body", "schema": { @@ -6865,9 +6869,13 @@ "operationId": "PostSpec", "parameters": [ { + "enum": [ + "registerWithInfo", + "registerWithCspSpecName" + ], "type": "string", - "description": "registerWithInfo or else", - "name": "registeringMethod", + "description": "registeringMethod", + "name": "action", "in": "query", "required": true }, @@ -6880,7 +6888,7 @@ "required": true }, { - "description": "Details for an spec object", + "description": "Specify details of a spec object (vCPU, memoryGiB, ...) manually", "name": "specInfo", "in": "body", "schema": { @@ -6888,7 +6896,7 @@ } }, { - "description": "name, connectionName and cspSpecName", + "description": "Specify name, connectionName and cspSpecName to register a spec object automatically", "name": "specName", "in": "body", "schema": { diff --git a/src/api/rest/docs/swagger.yaml b/src/api/rest/docs/swagger.yaml index 3afee333a..8e9665358 100644 --- a/src/api/rest/docs/swagger.yaml +++ b/src/api/rest/docs/swagger.yaml @@ -7251,23 +7251,28 @@ paths: description: Register image operationId: PostImage parameters: - - description: registeringMethod (registerWithInfo or registerWithId) + - description: registeringMethod + enum: + - registerWithInfo + - registerWithId in: query name: action required: true type: string - - default: ns01 + - default: system-purpose-common-ns description: Namespace ID in: path name: nsId required: true type: string - - description: Details for an image object + - description: Specify details of a image object (cspImageName, guestOS, description, + ...) manually in: body name: imageInfo schema: $ref: '#/definitions/mcir.TbImageInfo' - - description: name, connectionName and cspImageId + - description: Specify name, connectionName and cspImageId to register an image + object automatically in: body name: imageId schema: @@ -7791,9 +7796,12 @@ paths: description: Register spec operationId: PostSpec parameters: - - description: registerWithInfo or else + - description: registeringMethod + enum: + - registerWithInfo + - registerWithCspSpecName in: query - name: registeringMethod + name: action required: true type: string - default: system-purpose-common-ns @@ -7802,12 +7810,13 @@ paths: name: nsId required: true type: string - - description: Details for an spec object + - description: Specify details of a spec object (vCPU, memoryGiB, ...) manually in: body name: specInfo schema: $ref: '#/definitions/mcir.TbSpecInfo' - - description: name, connectionName and cspSpecName + - description: Specify name, connectionName and cspSpecName to register a spec + object automatically in: body name: specName schema: diff --git a/src/api/rest/server/mcir/image.go b/src/api/rest/server/mcir/image.go index e81ba0f0a..00aa1d62f 100644 --- a/src/api/rest/server/mcir/image.go +++ b/src/api/rest/server/mcir/image.go @@ -33,10 +33,10 @@ import ( // @Tags [Infra resource] MCIR Image management // @Accept json // @Produce json -// @Param action query string true "registeringMethod (registerWithInfo or registerWithId)" -// @Param nsId path string true "Namespace ID" default(ns01) -// @Param imageInfo body mcir.TbImageInfo false "Details for an image object" -// @Param imageId body mcir.TbImageReq false "name, connectionName and cspImageId" +// @Param action query string true "registeringMethod" Enums(registerWithInfo, registerWithId) +// @Param nsId path string true "Namespace ID" default(system-purpose-common-ns) +// @Param imageInfo body mcir.TbImageInfo false "Specify details of a image object (cspImageName, guestOS, description, ...) manually" +// @Param imageId body mcir.TbImageReq false "Specify name, connectionName and cspImageId to register an image object automatically" // @Param update query boolean false "Force update to existing image object" default(false) // @Success 200 {object} mcir.TbImageInfo // @Failure 404 {object} common.SimpleMsg diff --git a/src/api/rest/server/mcir/spec.go b/src/api/rest/server/mcir/spec.go index 7f38de500..7cdb4a4bf 100644 --- a/src/api/rest/server/mcir/spec.go +++ b/src/api/rest/server/mcir/spec.go @@ -33,10 +33,10 @@ import ( // @Tags [Infra resource] MCIR Spec management // @Accept json // @Produce json -// @Param registeringMethod query string true "registerWithInfo or else" +// @Param action query string true "registeringMethod" Enums(registerWithInfo, registerWithCspSpecName) // @Param nsId path string true "Namespace ID" default(system-purpose-common-ns) -// @Param specInfo body mcir.TbSpecInfo false "Details for an spec object" -// @Param specName body mcir.TbSpecReq false "name, connectionName and cspSpecName" +// @Param specInfo body mcir.TbSpecInfo false "Specify details of a spec object (vCPU, memoryGiB, ...) manually" +// @Param specName body mcir.TbSpecReq false "Specify name, connectionName and cspSpecName to register a spec object automatically" // @Param update query boolean false "Force update to existing spec object" default(false) // @Success 200 {object} mcir.TbSpecInfo // @Failure 404 {object} common.SimpleMsg