api: Add operation IDs

cloud-barista · Sep 9, 2024 · 004914a · 004914a
1 parent f3d628f
commit 004914a
Show file tree

Hide file tree

Showing 5 changed files with 72 additions and 52 deletions.
diff --git a/pkg/api/rest/controller/health.go b/pkg/api/rest/controller/health.go
@@ -11,15 +11,16 @@ var OkMessage = model.SimpleMsg{}
 var IsReady = false
 
 // CheckReady func is for checking Grasshopper server health.
-// @Summary Check Ready
-// @Description Check Grasshopper is ready
-// @Tags [Admin] System management
-// @Accept		json
-// @Produce		json
-// @Success		200 {object}	model.SimpleMsg			"Successfully get ready state."
-// @Failure		500	{object}	common.ErrorResponse	"Failed to check ready state."
 //
-// @Router		/readyz [get]
+//	@ID				health-check-readyz
+//	@Summary		Check Ready
+//	@Description	Check Grasshopper is ready
+//	@Tags [Admin]	System management
+//	@Accept			json
+//	@Produce		json
+//	@Success		200 {object}	model.SimpleMsg			"Successfully get ready state."
+//	@Failure		500	{object}	common.ErrorResponse	"Failed to check ready state."
+//	@Router		/readyz [get]
 func CheckReady(c echo.Context) error {
 	status := http.StatusOK
 

diff --git a/pkg/api/rest/controller/software.go b/pkg/api/rest/controller/software.go
@@ -56,17 +56,18 @@ func uploadHandler(c echo.Context) (string, error) {
 
 // RegisterSoftware godoc
 //
-// @Summary	Register Software
-// @Description	Register the software.<br><br>[JSON Body Example]<br>{"architecture":"x86_64","install_type":"ansible","match_names":["telegraf"],"name":"telegraf","os":"Ubuntu","os_version":"22.04","version":"1.0"}
-// @Tags		[Software]
-// @Accept		mpfd
-// @Produce		json
-// @Param		json formData string true "Software register request JSON body string."
-// @Param 		archive formData file true "Archive file to upload for ansible."
-// @Success		200	{object}	model.SoftwareRegisterReq	"Successfully registered the software."
-// @Failure		400	{object}	common.ErrorResponse		"Sent bad request."
-// @Failure		500	{object}	common.ErrorResponse		"Failed to sent SSH command."
-// @Router		/software/register [post]
+//	@ID				register-software
+//	@Summary		Register Software
+//	@Description	Register the software.<br><br>[JSON Body Example]<br>{"architecture":"x86_64","install_type":"ansible","match_names":["telegraf"],"name":"telegraf","os":"Ubuntu","os_version":"22.04","version":"1.0"}
+//	@Tags			[Software]
+//	@Accept			mpfd
+//	@Produce		json
+//	@Param			json formData string true "Software register request JSON body string."
+//	@Param 			archive formData file true "Archive file to upload for ansible."
+//	@Success		200	{object}	model.SoftwareRegisterReq	"Successfully registered the software."
+//	@Failure		400	{object}	common.ErrorResponse		"Sent bad request."
+//	@Failure		500	{object}	common.ErrorResponse		"Failed to sent SSH command."
+//	@Router			/software/register [post]
 func RegisterSoftware(c echo.Context) error {
 	err := c.Request().ParseMultipartForm(10 << 30) // 10GB
 	if err != nil {
@@ -163,16 +164,17 @@ func RegisterSoftware(c echo.Context) error {
 
 // GetExecutionList godoc
 //
-// @Summary	Get Execution List
-// @Description	Get software migration execution list.
-// @Tags		[Software]
-// @Accept		json
-// @Produce		json
-// @Param		getExecutionListReq body model.GetExecutionListReq true "Software info list."
-// @Success		200	{object}	model.GetExecutionListRes	"Successfully get migration execution list."
-// @Failure		400	{object}	common.ErrorResponse		"Sent bad request."
-// @Failure		500	{object}	common.ErrorResponse		"Failed to get migration execution list."
-// @Router		/software/execution_list [post]
+//	@ID				get-execution-list
+//	@Summary		Get Execution List
+//	@Description	Get software migration execution list.
+//	@Tags			[Software]
+//	@Accept			json
+//	@Produce		json
+//	@Param			getExecutionListReq body model.GetExecutionListReq true "Software info list."
+//	@Success		200	{object}	model.GetExecutionListRes	"Successfully get migration execution list."
+//	@Failure		400	{object}	common.ErrorResponse		"Sent bad request."
+//	@Failure		500	{object}	common.ErrorResponse		"Failed to get migration execution list."
+//	@Router			/software/execution_list [post]
 func GetExecutionList(c echo.Context) error {
 	var err error
 
@@ -192,16 +194,17 @@ func GetExecutionList(c echo.Context) error {
 
 // InstallSoftware godoc
 //
-// @Summary	Install Software
-// @Description	Install pieces of software to target.
-// @Tags		[Software]
-// @Accept		json
-// @Produce		json
-// @Param		softwareInstallReq body model.SoftwareInstallReq true "Software install request."
-// @Success		200	{object}	model.SoftwareInstallRes	"Successfully sent SSH command."
-// @Failure		400	{object}	common.ErrorResponse		"Sent bad request."
-// @Failure		500	{object}	common.ErrorResponse		"Failed to sent SSH command."
-// @Router		/software/install [post]
+//	@ID				install-software
+//	@Summary		Install Software
+//	@Description	Install pieces of software to target.
+//	@Tags			[Software]
+//	@Accept			json
+//	@Produce		json
+//	@Param			softwareInstallReq body model.SoftwareInstallReq true "Software install request."
+//	@Success		200	{object}	model.SoftwareInstallRes	"Successfully sent SSH command."
+//	@Failure		400	{object}	common.ErrorResponse		"Sent bad request."
+//	@Failure		500	{object}	common.ErrorResponse		"Failed to sent SSH command."
+//	@Router			/software/install [post]
 func InstallSoftware(c echo.Context) error {
 	softwareInstallReq := new(model.SoftwareInstallReq)
 	err := c.Bind(softwareInstallReq)
@@ -241,16 +244,17 @@ func InstallSoftware(c echo.Context) error {
 
 // DeleteSoftware godoc
 //
-// @Summary		Delete Software
-// @Description	Delete the software.
-// @Tags		[Software]
-// @Accept		json
-// @Produce		json
-// @Param		softwareId path string true "ID of the software."
-// @Success		200	{object}	model.SimpleMsg			"Successfully update the software"
-// @Failure		400	{object}	common.ErrorResponse	"Sent bad request."
-// @Failure		500	{object}	common.ErrorResponse	"Failed to delete the software"
-// @Router		/software/{softwareId} [delete]
+//	@ID				delete-software
+//	@Summary		Delete Software
+//	@Description	Delete the software.
+//	@Tags			[Software]
+//	@Accept			json
+//	@Produce		json
+//	@Param			softwareId path string true "ID of the software."
+//	@Success		200	{object}	model.SimpleMsg			"Successfully update the software"
+//	@Failure		400	{object}	common.ErrorResponse	"Sent bad request."
+//	@Failure		500	{object}	common.ErrorResponse	"Failed to delete the software"
+//	@Router			/software/{softwareId} [delete]
 func DeleteSoftware(c echo.Context) error {
 	swID := c.Param("softwareId")
 	if swID == "" {

diff --git a/pkg/api/rest/docs/docs.go b/pkg/api/rest/docs/docs.go
@@ -29,9 +29,10 @@ const docTemplate = `{
                     "application/json"
                 ],
                 "tags": [
-                    "[Admin] System management"
+                    "[Admin]\tSystem management"
                 ],
                 "summary": "Check Ready",
+                "operationId": "health-check-readyz",
                 "responses": {
                     "200": {
                         "description": "Successfully get ready state.",
@@ -61,6 +62,7 @@ const docTemplate = `{
                     "[Software]"
                 ],
                 "summary": "Get Execution List",
+                "operationId": "get-execution-list",
                 "parameters": [
                     {
                         "description": "Software info list.",
@@ -107,6 +109,7 @@ const docTemplate = `{
                     "[Software]"
                 ],
                 "summary": "Install Software",
+                "operationId": "install-software",
                 "parameters": [
                     {
                         "description": "Software install request.",
@@ -153,6 +156,7 @@ const docTemplate = `{
                     "[Software]"
                 ],
                 "summary": "Register Software",
+                "operationId": "register-software",
                 "parameters": [
                     {
                         "type": "string",
@@ -204,6 +208,7 @@ const docTemplate = `{
                     "[Software]"
                 ],
                 "summary": "Delete Software",
+                "operationId": "delete-software",
                 "parameters": [
                     {
                         "type": "string",

diff --git a/pkg/api/rest/docs/swagger.json b/pkg/api/rest/docs/swagger.json
@@ -22,9 +22,10 @@
                     "application/json"
                 ],
                 "tags": [
-                    "[Admin] System management"
+                    "[Admin]\tSystem management"
                 ],
                 "summary": "Check Ready",
+                "operationId": "health-check-readyz",
                 "responses": {
                     "200": {
                         "description": "Successfully get ready state.",
@@ -54,6 +55,7 @@
                     "[Software]"
                 ],
                 "summary": "Get Execution List",
+                "operationId": "get-execution-list",
                 "parameters": [
                     {
                         "description": "Software info list.",
@@ -100,6 +102,7 @@
                     "[Software]"
                 ],
                 "summary": "Install Software",
+                "operationId": "install-software",
                 "parameters": [
                     {
                         "description": "Software install request.",
@@ -146,6 +149,7 @@
                     "[Software]"
                 ],
                 "summary": "Register Software",
+                "operationId": "register-software",
                 "parameters": [
                     {
                         "type": "string",
@@ -197,6 +201,7 @@
                     "[Software]"
                 ],
                 "summary": "Delete Software",
+                "operationId": "delete-software",
                 "parameters": [
                     {
                         "type": "string",

diff --git a/pkg/api/rest/docs/swagger.yaml b/pkg/api/rest/docs/swagger.yaml
@@ -137,6 +137,7 @@ paths:
       consumes:
       - application/json
       description: Check Grasshopper is ready
+      operationId: health-check-readyz
       produces:
       - application/json
       responses:
@@ -150,12 +151,13 @@ paths:
             $ref: '#/definitions/github_com_cloud-barista_cm-grasshopper_pkg_api_rest_common.ErrorResponse'
       summary: Check Ready
       tags:
-      - '[Admin] System management'
+      - "[Admin]\tSystem management"
   /software/{softwareId}:
     delete:
       consumes:
       - application/json
       description: Delete the software.
+      operationId: delete-software
       parameters:
       - description: ID of the software.
         in: path
@@ -185,6 +187,7 @@ paths:
       consumes:
       - application/json
       description: Get software migration execution list.
+      operationId: get-execution-list
       parameters:
       - description: Software info list.
         in: body
@@ -215,6 +218,7 @@ paths:
       consumes:
       - application/json
       description: Install pieces of software to target.
+      operationId: install-software
       parameters:
       - description: Software install request.
         in: body
@@ -245,6 +249,7 @@ paths:
       consumes:
       - multipart/form-data
       description: Register the software.<br><br>[JSON Body Example]<br>{"architecture":"x86_64","install_type":"ansible","match_names":["telegraf"],"name":"telegraf","os":"Ubuntu","os_version":"22.04","version":"1.0"}
+      operationId: register-software
       parameters:
       - description: Software register request JSON body string.
         in: formData