From a083311d9017a53da78f5c5b9493a04ecaaadaf1 Mon Sep 17 00:00:00 2001 From: david may <1301201+wass3r@users.noreply.github.com> Date: Fri, 7 Jun 2024 13:29:04 -0500 Subject: [PATCH] fix(swagger): various fixes and improved consistency (#1139) --- api/admin/build.go | 30 ++++++++++++++++-------------- api/admin/clean.go | 15 +++++++-------- api/admin/deployment.go | 9 ++++++--- api/admin/hook.go | 23 +++++++++++++---------- api/admin/repo.go | 23 +++++++++++++---------- api/admin/rotate_keys.go | 8 ++++++-- api/admin/secret.go | 23 +++++++++++++---------- api/admin/service.go | 21 ++++++++++++--------- api/admin/settings.go | 33 ++++++++++++++++----------------- api/admin/step.go | 21 ++++++++++++--------- api/admin/user.go | 21 ++++++++++++--------- api/admin/worker.go | 4 ++++ api/auth/get_token.go | 8 ++++---- api/auth/login.go | 6 +++--- api/auth/logout.go | 6 +++++- api/auth/post_token.go | 7 +++---- api/auth/redirect.go | 10 +++++----- api/auth/validate_oauth.go | 6 +++--- api/badge.go | 16 ++++++++++++---- api/build/approve.go | 25 ++++++++++++------------- api/build/cancel.go | 26 +++++++++++++++----------- api/build/clean.go | 3 +-- api/build/create.go | 18 +++++++++--------- api/build/delete.go | 22 +++++++++++++++------- api/build/executable.go | 22 +++++++++++++--------- api/build/get.go | 24 ++++++++++++++++++------ api/build/get_id.go | 17 ++++++++++------- api/build/graph.go | 20 ++++++++++++-------- api/build/id_request_token.go | 18 +++++++++--------- api/build/id_token.go | 18 +++++++++--------- api/build/list_org.go | 19 +++++++++++-------- api/build/list_repo.go | 28 ++++++++++++++++++---------- api/build/plan.go | 2 +- api/build/restart.go | 18 +++++++++--------- api/build/token.go | 16 ++++++++++------ api/build/update.go | 24 ++++++++++++++++-------- api/dashboard/create.go | 12 ++++++------ api/dashboard/delete.go | 17 ++++++++++------- api/dashboard/doc.go | 8 ++++++++ api/dashboard/get.go | 22 +++++++++++++--------- api/dashboard/list_user.go | 10 +++++----- api/dashboard/update.go | 15 +++++++-------- api/deployment/create.go | 20 ++++++++++++++------ api/deployment/get.go | 21 ++++++++++++++------- api/deployment/list.go | 23 +++++++++++++++-------- api/health.go | 2 +- api/hook/create.go | 33 ++++++++++++++++++++------------- api/hook/delete.go | 19 +++++++++++-------- api/hook/doc.go | 8 ++++++++ api/hook/get.go | 21 ++++++++++++++------- api/hook/list.go | 24 ++++++++++++++++-------- api/hook/redeliver.go | 18 +++++++++++------- api/hook/update.go | 19 +++++++++++-------- api/jwks.go | 2 +- api/log/create_service.go | 18 +++++++++++++----- api/log/create_step.go | 18 +++++++++++++----- api/log/delete_service.go | 20 ++++++++++++++++---- api/log/delete_step.go | 20 ++++++++++++++++---- api/log/get_service.go | 23 +++++++++++++++++------ api/log/get_step.go | 23 +++++++++++++++++------ api/log/list_build.go | 23 +++++++++++++++++------ api/log/update_service.go | 24 +++++++++++++++--------- api/log/update_step.go | 24 +++++++++++++++--------- api/metrics.go | 4 ++-- api/oi_config.go | 2 +- api/pipeline/compile.go | 24 ++++++++++++++++-------- api/pipeline/create.go | 20 ++++++++++++-------- api/pipeline/delete.go | 21 ++++++++++++++------- api/pipeline/expand.go | 24 ++++++++++++++++-------- api/pipeline/get.go | 25 ++++++++++++++++++++----- api/pipeline/list.go | 24 ++++++++++++++++-------- api/pipeline/template.go | 28 +++++++++++++++++++--------- api/pipeline/update.go | 22 +++++++++++++++------- api/pipeline/validate.go | 24 ++++++++++++++++-------- api/queue/doc.go | 8 ++++++++ api/repo/chown.go | 24 ++++++++++++++++++------ api/repo/create.go | 15 +++++++++------ api/repo/delete.go | 25 ++++++++++++++++--------- api/repo/get.go | 21 ++++++++++++++++----- api/repo/list.go | 16 ++++++++++------ api/repo/list_org.go | 18 +++++++++++------- api/repo/repair.go | 20 ++++++++++++++++---- api/repo/update.go | 19 +++++++++++-------- api/schedule/create.go | 22 +++++++++++++++------- api/schedule/delete.go | 25 ++++++++++++++++--------- api/schedule/doc.go | 8 ++++++++ api/schedule/get.go | 21 ++++++++++++++++----- api/schedule/list.go | 23 +++++++++++++++-------- api/schedule/update.go | 21 ++++++++++++--------- api/scm/sync.go | 21 ++++++++++++++------- api/scm/sync_org.go | 18 +++++++++++++----- api/secret/create.go | 16 ++++++++++------ api/secret/delete.go | 12 ++++++++---- api/secret/get.go | 12 ++++++++---- api/secret/list.go | 19 +++++++++++-------- api/secret/update.go | 14 +++++++++----- api/service/create.go | 22 +++++++++++++++------- api/service/delete.go | 23 +++++++++++++++++------ api/service/get.go | 21 ++++++++++++++------- api/service/list.go | 23 +++++++++++++++-------- api/service/plan.go | 2 +- api/service/update.go | 22 +++++++++++++++------- api/step/create.go | 20 ++++++++++++++------ api/step/delete.go | 21 ++++++++++++++++----- api/step/get.go | 21 ++++++++++++++++----- api/step/list.go | 23 +++++++++++++++-------- api/step/plan.go | 2 +- api/step/update.go | 20 ++++++++++++++------ api/user/create.go | 15 +++++++++------ api/user/create_token.go | 6 +++++- api/user/delete.go | 15 +++++++++------ api/user/delete_token.go | 8 ++++++-- api/user/get.go | 11 +++++++---- api/user/get_current.go | 8 ++++++-- api/user/get_source.go | 11 +++++++---- api/user/list.go | 15 +++++++++------ api/user/update.go | 17 ++++++++++------- api/user/update_current.go | 14 +++++++------- api/version.go | 2 +- api/webhook/post.go | 10 +++++----- api/worker/create.go | 14 +++++++++----- api/worker/delete.go | 21 ++++++++++++++++----- api/worker/get.go | 19 +++++++++++++++---- api/worker/list.go | 19 +++++++++++++------ api/worker/refresh.go | 12 ++++++++---- api/worker/update.go | 16 ++++++++++------ 126 files changed, 1399 insertions(+), 767 deletions(-) create mode 100644 api/dashboard/doc.go create mode 100644 api/hook/doc.go create mode 100644 api/queue/doc.go create mode 100644 api/schedule/doc.go diff --git a/api/admin/build.go b/api/admin/build.go index 1a4fe0489..aab5f4fca 100644 --- a/api/admin/build.go +++ b/api/admin/build.go @@ -19,7 +19,7 @@ import ( // swagger:operation GET /api/v1/admin/builds/queue admin AllBuildsQueue // -// Get all of the running and pending builds in the database +// Get running and pending builds // // --- // produces: @@ -38,14 +38,17 @@ import ( // schema: // type: array // items: -// "$ref": "#/definitions/BuildQueue" +// "$ref": "#/definitions/QueueBuild" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve all running and pending builds from the database +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// AllBuildsQueue represents the API handler to -// capture all running and pending builds stored in the database. +// AllBuildsQueue represents the API handler to get running and pending builds. func AllBuildsQueue(c *gin.Context) { // capture middleware values ctx := c.Request.Context() @@ -70,7 +73,7 @@ func AllBuildsQueue(c *gin.Context) { // swagger:operation PUT /api/v1/admin/build admin AdminUpdateBuild // -// Update a build in the database +// Update a build // // --- // produces: @@ -78,7 +81,7 @@ func AllBuildsQueue(c *gin.Context) { // parameters: // - in: body // name: body -// description: Payload containing build to update +// description: The build object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Build" @@ -86,20 +89,19 @@ func AllBuildsQueue(c *gin.Context) { // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully updated the build in the database +// description: Successfully updated the build // schema: // "$ref": "#/definitions/Build" -// '404': -// description: Unable to update the build in the database +// '400': +// description: Invalid request payload // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the build in the database +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateBuild represents the API handler to -// update any build stored in the database. +// UpdateBuild represents the API handler to update a build. func UpdateBuild(c *gin.Context) { logrus.Info("Admin: updating build in database") @@ -113,7 +115,7 @@ func UpdateBuild(c *gin.Context) { if err != nil { retErr := fmt.Errorf("unable to decode JSON for build %d: %w", input.GetID(), err) - util.HandleError(c, http.StatusNotFound, retErr) + util.HandleError(c, http.StatusBadRequest, retErr) return } diff --git a/api/admin/clean.go b/api/admin/clean.go index 9813a7fc7..d6ecbde4d 100644 --- a/api/admin/clean.go +++ b/api/admin/clean.go @@ -20,7 +20,7 @@ import ( // swagger:operation PUT /api/v1/admin/clean admin AdminCleanResources // -// Update pending build resources to error status before a given time +// Update stale build resources to error status // // --- // produces: @@ -28,7 +28,7 @@ import ( // parameters: // - in: query // name: before -// description: filter pending resources created before a certain time +// description: Filter stale resources created before a certain time // required: true // type: integer // - in: body @@ -43,22 +43,21 @@ import ( // '200': // description: Successfully updated pending resources with error message // schema: -// type: string +// type: string // '400': -// description: Unable to update resources — bad request +// description: Invalid request payload // schema: // "$ref": "#/definitions/Error" // '401': -// description: Unable to update resources — unauthorized +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update resources +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// CleanResources represents the API handler to -// update any user stored in the database. +// CleanResources represents the API handler to update stale resources. func CleanResources(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/admin/deployment.go b/api/admin/deployment.go index deeac0045..f205c90d1 100644 --- a/api/admin/deployment.go +++ b/api/admin/deployment.go @@ -10,20 +10,23 @@ import ( // swagger:operation PUT /api/v1/admin/deployment admin AdminUpdateDeployment // -// Get All (Not Implemented) +// Update a deployment (Not Implemented) // // --- // produces: // - application/json // parameters: // responses: +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '501': // description: This endpoint is not implemented // schema: // type: string -// UpdateDeployment represents the API handler to -// update any deployment stored in the database. +// UpdateDeployment represents the API handler to update a deployment. func UpdateDeployment(c *gin.Context) { c.JSON(http.StatusNotImplemented, "The server does not support the functionality required to fulfill the request.") } diff --git a/api/admin/hook.go b/api/admin/hook.go index 156110880..d9d7b4b17 100644 --- a/api/admin/hook.go +++ b/api/admin/hook.go @@ -17,7 +17,7 @@ import ( // swagger:operation PUT /api/v1/admin/hook admin AdminUpdateHook // -// Update a hook in the database +// Update a hook // // --- // produces: @@ -25,7 +25,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing hook to update +// description: The hook object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Webhook" @@ -33,20 +33,23 @@ import ( // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully updated the hook in the database +// description: Successfully updated the hook // schema: // "$ref": "#/definitions/Webhook" -// '404': -// description: Unable to update the hook in the database +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" -// '501': -// description: Unable to update the hook in the database +// '400': +// description: Invalid request payload +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateHook represents the API handler to -// update any hook stored in the database. +// UpdateHook represents the API handler to update a hook. func UpdateHook(c *gin.Context) { logrus.Info("Admin: updating hook in database") @@ -60,7 +63,7 @@ func UpdateHook(c *gin.Context) { if err != nil { retErr := fmt.Errorf("unable to decode JSON for hook %d: %w", input.GetID(), err) - util.HandleError(c, http.StatusNotFound, retErr) + util.HandleError(c, http.StatusBadRequest, retErr) return } diff --git a/api/admin/repo.go b/api/admin/repo.go index 52da52301..6ce1bac37 100644 --- a/api/admin/repo.go +++ b/api/admin/repo.go @@ -17,7 +17,7 @@ import ( // swagger:operation PUT /api/v1/admin/repo admin AdminUpdateRepo // -// Update a repo in the database +// Update a repository // // --- // produces: @@ -25,7 +25,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing repo to update +// description: The repository object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Repo" @@ -33,20 +33,23 @@ import ( // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully updated the repo in the database +// description: Successfully updated the repo // schema: // "$ref": "#/definitions/Repo" -// '404': -// description: Unable to update the repo in the database +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" -// '501': -// description: Unable to update the repo in the database +// '400': +// description: Invalid request payload +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateRepo represents the API handler to -// update any repo stored in the database. +// UpdateRepo represents the API handler to update a repo. func UpdateRepo(c *gin.Context) { logrus.Info("Admin: updating repo in database") @@ -60,7 +63,7 @@ func UpdateRepo(c *gin.Context) { if err != nil { retErr := fmt.Errorf("unable to decode JSON for repo %d: %w", input.GetID(), err) - util.HandleError(c, http.StatusNotFound, retErr) + util.HandleError(c, http.StatusBadRequest, retErr) return } diff --git a/api/admin/rotate_keys.go b/api/admin/rotate_keys.go index 56681a60c..0186c0c29 100644 --- a/api/admin/rotate_keys.go +++ b/api/admin/rotate_keys.go @@ -28,13 +28,17 @@ import ( // description: Successfully rotated OIDC provider keys // schema: // type: string +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Error unable to rotate OIDC provider keys +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // RotateOIDCKeys represents the API handler to -// rotate RSA keys in OIDC provider service. +// rotate RSA keys in the OIDC provider service. func RotateOIDCKeys(c *gin.Context) { logrus.Info("Admin: rotating keys for OIDC provider") diff --git a/api/admin/secret.go b/api/admin/secret.go index f9573d9dd..673134ba6 100644 --- a/api/admin/secret.go +++ b/api/admin/secret.go @@ -17,7 +17,7 @@ import ( // swagger:operation PUT /api/v1/admin/secret admin AdminUpdateSecret // -// Update a secret in the database +// Update a secret // // --- // produces: @@ -25,7 +25,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing secret to update +// description: The secret object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Secret" @@ -33,20 +33,23 @@ import ( // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully updated the secret in the database +// description: Successfully updated the secret // schema: // "$ref": "#/definitions/Secret" -// '404': -// description: Unable to update the secret in the database +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" -// '501': -// description: Unable to update the secret in the database +// '400': +// description: Invalid request payload +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateSecret represents the API handler to -// update any secret stored in the database. +// UpdateSecret represents the API handler to update a secret. func UpdateSecret(c *gin.Context) { logrus.Info("Admin: updating secret in database") @@ -60,7 +63,7 @@ func UpdateSecret(c *gin.Context) { if err != nil { retErr := fmt.Errorf("unable to decode JSON for secret %d: %w", input.GetID(), err) - util.HandleError(c, http.StatusNotFound, retErr) + util.HandleError(c, http.StatusBadRequest, retErr) return } diff --git a/api/admin/service.go b/api/admin/service.go index 4d74fb388..61153ad5f 100644 --- a/api/admin/service.go +++ b/api/admin/service.go @@ -17,7 +17,7 @@ import ( // swagger:operation PUT /api/v1/admin/service admin AdminUpdateService // -// Update a hook in the database +// Update a service // // --- // produces: @@ -25,7 +25,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing service to update +// description: The service object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Service" @@ -33,21 +33,24 @@ import ( // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully updated the service in the database +// description: Successfully updated the service // type: json // schema: // "$ref": "#/definitions/Service" -// '404': -// description: Unable to update the service in the database +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '400': +// description: Invalid request payload // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the service in the database +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateService represents the API handler to -// update any service stored in the database. +// UpdateService represents the API handler to update a service. func UpdateService(c *gin.Context) { logrus.Info("Admin: updating service in database") @@ -61,7 +64,7 @@ func UpdateService(c *gin.Context) { if err != nil { retErr := fmt.Errorf("unable to decode JSON for service %d: %w", input.GetID(), err) - util.HandleError(c, http.StatusNotFound, retErr) + util.HandleError(c, http.StatusBadRequest, retErr) return } diff --git a/api/admin/settings.go b/api/admin/settings.go index f04109680..8b5c525d8 100644 --- a/api/admin/settings.go +++ b/api/admin/settings.go @@ -23,7 +23,7 @@ import ( // swagger:operation GET /api/v1/admin/settings admin GetSettings // -// Get the currently configured settings. +// Get platform settings // // --- // produces: @@ -41,12 +41,11 @@ import ( // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve settings +// description: Not found // schema: // "$ref": "#/definitions/Error" -// GetSettings represents the API handler to -// captures settings stored in the database. +// GetSettings represents the API handler to get platform settings. func GetSettings(c *gin.Context) { // capture middleware values s := sMiddleware.FromContext(c) @@ -68,7 +67,7 @@ func GetSettings(c *gin.Context) { // swagger:operation PUT /api/v1/admin/settings admin UpdateSettings // -// Update the platform settings singleton in the database. +// Update platform settings // // --- // produces: @@ -76,7 +75,7 @@ func GetSettings(c *gin.Context) { // parameters: // - in: body // name: body -// description: Payload containing settings to update +// description: The settings object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Platform" @@ -84,12 +83,12 @@ func GetSettings(c *gin.Context) { // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully updated platform settings in the database +// description: Successfully updated platform settings // type: json // schema: // "$ref": "#/definitions/Platform" // '400': -// description: Unable to update settings — bad request +// description: Invalid request payload // schema: // "$ref": "#/definitions/Error" // '401': @@ -97,16 +96,16 @@ func GetSettings(c *gin.Context) { // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve platform settings to update +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update platform settings in the database +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateSettings represents the API handler to -// update the settings singleton stored in the database. +// UpdateSettings represents the API handler to update the +// platform settings singleton. func UpdateSettings(c *gin.Context) { // capture middleware values s := sMiddleware.FromContext(c) @@ -201,7 +200,7 @@ func UpdateSettings(c *gin.Context) { // swagger:operation DELETE /api/v1/admin/settings admin RestoreSettings // -// Restore the currently configured settings to the environment defaults. +// Restore platform settings to the environment defaults // // --- // produces: @@ -210,7 +209,7 @@ func UpdateSettings(c *gin.Context) { // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully restored default settings in the database +// description: Successfully restored default platform settings // type: json // schema: // "$ref": "#/definitions/Platform" @@ -219,16 +218,16 @@ func UpdateSettings(c *gin.Context) { // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve settings to restore +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to restore settings in the database +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // RestoreSettings represents the API handler to -// restore settings stored in the database to the environment defaults. +// restore platform settings to the environment defaults. func RestoreSettings(c *gin.Context) { // capture middleware values s := sMiddleware.FromContext(c) diff --git a/api/admin/step.go b/api/admin/step.go index aeb2e1f4b..b2250b9ec 100644 --- a/api/admin/step.go +++ b/api/admin/step.go @@ -16,7 +16,7 @@ import ( // swagger:operation PUT /api/v1/admin/step admin AdminUpdateStep // -// Update a step in the database +// Update a step // // --- // produces: @@ -24,7 +24,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing step to update +// description: The step object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Step" @@ -32,20 +32,23 @@ import ( // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully updated the step in the database +// description: Successfully updated the step // schema: // "$ref": "#/definitions/Step" -// '404': -// description: Unable to update the step in the database +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '400': +// description: Invalid request payload // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the step in the database +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateStep represents the API handler to -// update any step stored in the database. +// UpdateStep represents the API handler to update a step. func UpdateStep(c *gin.Context) { logrus.Info("Admin: updating step in database") @@ -57,7 +60,7 @@ func UpdateStep(c *gin.Context) { if err != nil { retErr := fmt.Errorf("unable to decode JSON for step %d: %w", input.GetID(), err) - util.HandleError(c, http.StatusNotFound, retErr) + util.HandleError(c, http.StatusBadRequest, retErr) return } diff --git a/api/admin/user.go b/api/admin/user.go index 7e5db6072..c8b0482a3 100644 --- a/api/admin/user.go +++ b/api/admin/user.go @@ -17,7 +17,7 @@ import ( // swagger:operation PUT /api/v1/admin/user admin AdminUpdateUser // -// Update a user in the database +// Update a user // // --- // produces: @@ -25,7 +25,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing user to update +// description: The user object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/User" @@ -33,20 +33,23 @@ import ( // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully updated the user in the database +// description: Successfully updated the user // schema: // "$ref": "#/definitions/User" -// '404': -// description: Unable to update the user in the database +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '400': +// description: Invalid request payload // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the user in the database +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateUser represents the API handler to -// update any user stored in the database. +// UpdateUser represents the API handler to update a user. func UpdateUser(c *gin.Context) { logrus.Info("Admin: updating user in database") @@ -60,7 +63,7 @@ func UpdateUser(c *gin.Context) { if err != nil { retErr := fmt.Errorf("unable to decode JSON for user %d: %w", input.GetID(), err) - util.HandleError(c, http.StatusNotFound, retErr) + util.HandleError(c, http.StatusBadRequest, retErr) return } diff --git a/api/admin/worker.go b/api/admin/worker.go index 82d7e9b5c..36be236ac 100644 --- a/api/admin/worker.go +++ b/api/admin/worker.go @@ -40,6 +40,10 @@ import ( // description: Unauthorized // schema: // "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error +// schema: +// "$ref": "#/definitions/Error" // RegisterToken represents the API handler to // generate a registration token for onboarding a worker. diff --git a/api/auth/get_token.go b/api/auth/get_token.go index 82fe08892..83adef396 100644 --- a/api/auth/get_token.go +++ b/api/auth/get_token.go @@ -26,15 +26,15 @@ import ( // parameters: // - in: query // name: code -// description: the code received after identity confirmation +// description: The code received after identity confirmation // type: string // - in: query // name: state -// description: a random string +// description: A random string // type: string // - in: query // name: redirect_uri -// description: the url where the user will be sent after authorization +// description: The URL where the user will be sent after authorization // type: string // responses: // '200': @@ -47,7 +47,7 @@ import ( // '307': // description: Redirected for authentication // '401': -// description: Unable to authenticate +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '503': diff --git a/api/auth/login.go b/api/auth/login.go index 3c6edcaa4..05b975f8d 100644 --- a/api/auth/login.go +++ b/api/auth/login.go @@ -16,20 +16,20 @@ import ( // swagger:operation GET /login authenticate GetLogin // -// Log into the Vela api +// Log into the Vela API // // --- // parameters: // - in: query // name: type -// description: the login type ("cli" or "web") +// description: The login type ("cli" or "web") // type: string // enum: // - web // - cli // - in: query // name: port -// description: the port number when type=cli +// description: The port number when type=cli // type: integer // responses: // '307': diff --git a/api/auth/logout.go b/api/auth/logout.go index ad21740ed..8c0af25fa 100644 --- a/api/auth/logout.go +++ b/api/auth/logout.go @@ -19,7 +19,7 @@ import ( // swagger:operation GET /logout authenticate GetLogout // -// Log out of the Vela api +// Log out of the Vela API // // --- // produces: @@ -29,6 +29,10 @@ import ( // description: Successfully logged out // schema: // type: string +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '503': // description: Logout did not succeed // schema: diff --git a/api/auth/post_token.go b/api/auth/post_token.go index 40ffbf99a..929ef17ca 100644 --- a/api/auth/post_token.go +++ b/api/auth/post_token.go @@ -36,7 +36,7 @@ import ( // schema: // "$ref": "#/definitions/Token" // '401': -// description: Unable to authenticate +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '503': @@ -44,9 +44,8 @@ import ( // schema: // "$ref": "#/definitions/Error" -// PostAuthToken represents the API handler to -// process a user logging in using PAT to Vela from -// the API. +// PostAuthToken represents the API handler to process +// a user logging in using PAT to Vela from the API. func PostAuthToken(c *gin.Context) { // capture middleware values ctx := c.Request.Context() diff --git a/api/auth/redirect.go b/api/auth/redirect.go index dcaba1844..7837ca07e 100644 --- a/api/auth/redirect.go +++ b/api/auth/redirect.go @@ -25,11 +25,11 @@ import ( // parameters: // - in: query // name: code -// description: the code received after identity confirmation +// description: The code received after identity confirmation // type: string // - in: query // name: state -// description: a random string +// description: A random string // type: string // responses: // '307': @@ -48,15 +48,15 @@ import ( // - in: path // name: port // required: true -// description: the port number +// description: The port number // type: integer // - in: query // name: code -// description: the code received after identity confirmation +// description: The code received after identity confirmation // type: string // - in: query // name: state -// description: a random string +// description: A random string // type: string // responses: // '307': diff --git a/api/auth/validate_oauth.go b/api/auth/validate_oauth.go index 399d3e2e2..94af8ca86 100644 --- a/api/auth/validate_oauth.go +++ b/api/auth/validate_oauth.go @@ -14,7 +14,7 @@ import ( // swagger:operation GET /validate-oauth authenticate ValidateOAuthToken // -// Validate that a user oauth token was created by Vela +// Validate that a user OAuth token was created by Vela // // --- // produces: @@ -32,12 +32,12 @@ import ( // schema: // "$ref": "#/definitions/Token" // '401': -// description: Unable to validate +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // ValidateOAuthToken represents the API handler to -// validate that a user oauth token was created by Vela. +// validate that a user OAuth token was created by Vela. func ValidateOAuthToken(c *gin.Context) { // capture middleware values ctx := c.Request.Context() diff --git a/api/badge.go b/api/badge.go index 4f3dfc380..c926c64f3 100644 --- a/api/badge.go +++ b/api/badge.go @@ -17,7 +17,7 @@ import ( // swagger:operation GET /badge/{org}/{repo}/status.svg base GetBadge // -// Get a badge for the repo +// Get a build status badge for a repository // // --- // produces: @@ -25,19 +25,27 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org the repo belongs to +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo to get the badge for +// description: Name of the repository // required: true // type: string // responses: // '200': -// description: Successfully retrieved a status Badge +// description: Successfully retrieved the build status badge // schema: // type: string +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // GetBadge represents the API handler to // return a build status badge. diff --git a/api/build/approve.go b/api/build/approve.go index 16c1fcc65..cc7159d53 100644 --- a/api/build/approve.go +++ b/api/build/approve.go @@ -24,7 +24,7 @@ import ( // swagger:operation POST /api/v1/repos/{org}/{repo}/builds/{build}/approve builds ApproveBuild // -// Sign off on a build to run from an outside contributor +// Approve a build to run // // --- // produces: @@ -32,17 +32,17 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path // name: build -// description: Build number to retrieve +// description: Build number // required: true // type: integer // security: @@ -52,25 +52,24 @@ import ( // description: Request processed but build was skipped // schema: // type: string -// '201': -// description: Successfully created the build -// type: json -// schema: -// "$ref": "#/definitions/Build" // '400': -// description: Unable to create the build +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to create the build +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the build +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ApproveBuild represents the API handler to approve a build to run in the configured backend. +// ApproveBuild represents the API handler to approve a build to run. func ApproveBuild(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/build/cancel.go b/api/build/cancel.go index afad5d0e0..e4ee0b84e 100644 --- a/api/build/cancel.go +++ b/api/build/cancel.go @@ -26,25 +26,25 @@ import ( // swagger:operation DELETE /api/v1/repos/{org}/{repo}/builds/{build}/cancel builds CancelBuild // -// Cancel a running build +// Cancel a build // // --- // produces: // - application/json // parameters: // - in: path -// name: repo -// description: Name of the repo +// name: org +// description: Name of the organization // required: true // type: string // - in: path -// name: org -// description: Name of the org +// name: repo +// description: Name of the repository // required: true // type: string // - in: path // name: build -// description: Build number to cancel +// description: Build number // required: true // type: integer // security: @@ -53,21 +53,25 @@ import ( // '200': // description: Successfully canceled the build // schema: -// type: string +// "$ref": "#/definitions/Build" // '400': -// description: Unable to cancel build +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to cancel build +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to cancel build +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// CancelBuild represents the API handler to cancel a running build. +// CancelBuild represents the API handler to cancel a build. // //nolint:funlen // ignore statement count func CancelBuild(c *gin.Context) { diff --git a/api/build/clean.go b/api/build/clean.go index 235efc989..8473c25e1 100644 --- a/api/build/clean.go +++ b/api/build/clean.go @@ -17,8 +17,7 @@ import ( // cleanBuild is a helper function to kill the build // without execution. This will kill all resources, -// like steps and services, for the build in the -// configured backend. +// like steps and services, for the build. func CleanBuild(ctx context.Context, database database.Interface, b *types.Build, services []*library.Service, steps []*library.Step, e error) { // update fields in build object b.SetError(fmt.Sprintf("unable to publish to queue: %s", e.Error())) diff --git a/api/build/create.go b/api/build/create.go index f5782d331..e3745cfeb 100644 --- a/api/build/create.go +++ b/api/build/create.go @@ -23,7 +23,7 @@ import ( // swagger:operation POST /api/v1/repos/{org}/{repo}/builds builds CreateBuild // -// Create a build in the configured backend +// Create a build // // --- // produces: @@ -31,17 +31,17 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: body // name: body -// description: Payload containing the build to create +// description: Build object to create // required: true // schema: // "$ref": "#/definitions/Build" @@ -58,15 +58,15 @@ import ( // schema: // "$ref": "#/definitions/Build" // '400': -// description: Malformed request payload or improper pipeline configuration +// description: Invalid request payload or path // schema: // "$ref": "#/definitions/Error" // '401': -// description: Repository owner does not have proper access +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to find resources for build +// description: Not found // schema: // "$ref": "#/definitions/Error" // '429': @@ -74,11 +74,11 @@ import ( // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to receive the request or internal error while processing +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// CreateBuild represents the API handler to create a build in the configured backend. +// CreateBuild represents the API handler to create a build. func CreateBuild(c *gin.Context) { // capture middleware values m := c.MustGet("metadata").(*internal.Metadata) diff --git a/api/build/delete.go b/api/build/delete.go index 3da622da0..e4330ecc2 100644 --- a/api/build/delete.go +++ b/api/build/delete.go @@ -19,7 +19,7 @@ import ( // swagger:operation DELETE /api/v1/repos/{org}/{repo}/builds/{build} builds DeleteBuild // -// Delete a build in the configured backend +// Delete a build // // --- // produces: @@ -27,17 +27,17 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path // name: build -// description: Build number to delete +// description: Build number // required: true // type: integer // security: @@ -48,16 +48,24 @@ import ( // schema: // type: string // '400': -// description: Unable to delete the build +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to delete the build +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // DeleteBuild represents the API handler to remove -// a build for a repo from the configured backend. +// a build for a repo. func DeleteBuild(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/build/executable.go b/api/build/executable.go index 324984b10..a5d250cbc 100644 --- a/api/build/executable.go +++ b/api/build/executable.go @@ -24,7 +24,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/executable builds GetBuildExecutable // -// Get a build executable in the configured backend +// Get a build executable // // --- // produces: @@ -32,17 +32,17 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path // name: build -// description: Build number to retrieve +// description: Build number // required: true // type: integer // security: @@ -52,22 +52,26 @@ import ( // description: Successfully retrieved the build executable // type: json // schema: -// "$ref": "#/definitions/Build" +// "$ref": "#/definitions/BuildExecutable" // '400': -// description: Bad request +// description: Invalid request payload or path // schema: // "$ref": "#/definitions/Error" // '401': // description: Unauthorized // schema: // "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Could not retrieve build executable +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// GetBuildExecutable represents the API handler to capture -// a build executable for a repo from the configured backend. +// GetBuildExecutable represents the API handler to get +// a build executable for a repository. func GetBuildExecutable(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/build/get.go b/api/build/get.go index afa0994d6..df8c87bfd 100644 --- a/api/build/get.go +++ b/api/build/get.go @@ -16,7 +16,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build} builds GetBuild // -// Get a build in the configured backend +// Get a build // // --- // produces: @@ -24,17 +24,17 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path // name: build -// description: Build number to retrieve +// description: Build number // required: true // type: integer // security: @@ -45,9 +45,21 @@ import ( // type: json // schema: // "$ref": "#/definitions/Build" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" -// GetBuild represents the API handler to capture -// a build for a repo from the configured backend. +// GetBuild represents the API handler to get +// a build for a repository. func GetBuild(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/build/get_id.go b/api/build/get_id.go index d0a72191d..f27fde5f2 100644 --- a/api/build/get_id.go +++ b/api/build/get_id.go @@ -18,7 +18,7 @@ import ( // swagger:operation GET /api/v1/search/builds/{id} builds GetBuildByID // -// Get a single build by its id in the configured backend +// Get a build by id // // --- // produces: @@ -26,7 +26,7 @@ import ( // parameters: // - in: path // name: id -// description: build id +// description: Build ID // required: true // type: number // security: @@ -37,16 +37,20 @@ import ( // schema: // "$ref": "#/definitions/Build" // '400': -// description: Unable to retrieve the build +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the build +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// GetBuildByID represents the API handler to capture a -// build by its id from the configured backend. +// GetBuildByID represents the API handler to get a +// build by its id. func GetBuildByID(c *gin.Context) { // Capture user from middleware u := user.Retrieve(c) @@ -54,7 +58,6 @@ func GetBuildByID(c *gin.Context) { // Parse build ID from path id, err := strconv.ParseInt(c.Param("id"), 10, 64) - if err != nil { retErr := fmt.Errorf("unable to parse build id: %w", err) diff --git a/api/build/graph.go b/api/build/graph.go index 454cdd27a..e7207625c 100644 --- a/api/build/graph.go +++ b/api/build/graph.go @@ -91,7 +91,7 @@ const ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/graph builds GetBuildGraph // -// Get directed a-cyclical graph for a build in the configured backend +// Get directed a-cyclical graph for a build // // --- // produces: @@ -99,12 +99,12 @@ const ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -120,21 +120,25 @@ const ( // type: json // schema: // "$ref": "#/definitions/Graph" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" // '401': -// description: Unable to retrieve graph for the build — unauthorized +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve graph for the build — not found +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve graph for the build +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// GetBuildGraph represents the API handler to capture a -// directed a-cyclical graph for a build from the configured backend. +// GetBuildGraph represents the API handler to get a +// directed a-cyclical graph for a build. // //nolint:funlen,goconst,gocyclo // ignore function length and constants func GetBuildGraph(c *gin.Context) { diff --git a/api/build/id_request_token.go b/api/build/id_request_token.go index f5e3c9f93..1af34ce59 100644 --- a/api/build/id_request_token.go +++ b/api/build/id_request_token.go @@ -22,20 +22,20 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/id_request_token builds GetIDRequestToken // -// Get a Vela OIDC request token associated with a build +// Get a Vela OIDC request token for a build // // --- // produces: // - application/json // parameters: // - in: path -// name: repo -// description: Name of the repo +// name: org +// description: Name of the organization // required: true // type: string // - in: path -// name: org -// description: Name of the org +// name: repo +// description: Name of the repository // required: true // type: string // - in: path @@ -63,19 +63,19 @@ import ( // schema: // "$ref": "#/definitions/Token" // '400': -// description: Bad request +// description: Invalid request payload or path // schema: // "$ref": "#/definitions/Error" // '401': -// description: Unauthorized request +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to find build +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to generate ID request token +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/build/id_token.go b/api/build/id_token.go index a2b7fdab7..54744e983 100644 --- a/api/build/id_token.go +++ b/api/build/id_token.go @@ -20,20 +20,20 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/id_token builds GetIDToken // -// Get a Vela OIDC token associated with a build +// Get a Vela OIDC token for a build // // --- // produces: // - application/json // parameters: // - in: path -// name: repo -// description: Name of the repo +// name: org +// description: Name of the organization // required: true // type: string // - in: path -// name: org -// description: Name of the org +// name: repo +// description: Name of the repository // required: true // type: string // - in: path @@ -56,19 +56,19 @@ import ( // schema: // "$ref": "#/definitions/Token" // '400': -// description: Bad request +// description: Invalid request payload or path // schema: // "$ref": "#/definitions/Error" // '401': -// description: Unauthorized request +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to find build +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to generate id token +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/build/list_org.go b/api/build/list_org.go index a8e491a47..ff516c39c 100644 --- a/api/build/list_org.go +++ b/api/build/list_org.go @@ -22,7 +22,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/builds builds ListBuildsForOrg // -// Get a list of builds by org in the configured backend +// Get all builds for an organization // // --- // produces: @@ -30,7 +30,7 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: query @@ -85,19 +85,23 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the list of builds +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the list of builds +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListBuildsForOrg represents the API handler to capture a -// list of builds associated with an org from the configured backend. +// ListBuildsForOrg represents the API handler to get a +// list of builds associated with an organization. func ListBuildsForOrg(c *gin.Context) { // variables that will hold the build list, build list filters and total count var ( @@ -201,7 +205,6 @@ func ListBuildsForOrg(c *gin.Context) { // send API call to capture the list of builds for the org (and event type if passed in) b, t, err = database.FromContext(c).ListBuildsForOrg(ctx, o, filters, page, perPage) - if err != nil { retErr := fmt.Errorf("unable to list builds for org %s: %w", o, err) diff --git a/api/build/list_repo.go b/api/build/list_repo.go index 9c3fca345..f631e68ef 100644 --- a/api/build/list_repo.go +++ b/api/build/list_repo.go @@ -23,7 +23,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds builds ListBuildsForRepo // -// Get builds from the configured backend +// Get all builds for a repository // // --- // produces: @@ -31,12 +31,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: query @@ -83,12 +83,12 @@ import ( // default: 10 // - in: query // name: before -// description: filter builds created before a certain time +// description: Filter builds created before a certain time // type: integer // default: 1 // - in: query // name: after -// description: filter builds created after a certain time +// description: Filter builds created after a certain time // type: integer // default: 0 // security: @@ -105,19 +105,27 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the list of builds +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the list of builds +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListBuildsForRepo represents the API handler to capture a -// list of builds for a repo from the configured backend. +// ListBuildsForRepo represents the API handler to get a +// list of builds for a repository. func ListBuildsForRepo(c *gin.Context) { // variables that will hold the build list, build list filters and total count var ( diff --git a/api/build/plan.go b/api/build/plan.go index 49e700d52..f7c23b971 100644 --- a/api/build/plan.go +++ b/api/build/plan.go @@ -17,7 +17,7 @@ import ( // PlanBuild is a helper function to plan the build for // execution. This creates all resources, like steps -// and services, for the build in the configured backend. +// and services, for the build. // TODO: // - return build and error. func PlanBuild(ctx context.Context, database database.Interface, scm scm.Service, p *pipeline.Build, b *types.Build, r *types.Repo) error { diff --git a/api/build/restart.go b/api/build/restart.go index f8798fbb6..4cf0a21e0 100644 --- a/api/build/restart.go +++ b/api/build/restart.go @@ -26,7 +26,7 @@ import ( // swagger:operation POST /api/v1/repos/{org}/{repo}/builds/{build} builds RestartBuild // -// Restart a build in the configured backend +// Restart a build // // --- // produces: @@ -34,17 +34,17 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path // name: build -// description: Build number to restart +// description: Build number // required: true // type: integer // security: @@ -60,15 +60,15 @@ import ( // schema: // "$ref": "#/definitions/Build" // '400': -// description: Malformed request payload or improper pipeline configuration +// description: Invalid request payload or path // schema: // "$ref": "#/definitions/Error" // '401': -// description: Repository owner does not have proper access +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to find resources for build +// description: Not found // schema: // "$ref": "#/definitions/Error" // '429': @@ -76,11 +76,11 @@ import ( // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to receive the request or internal error while processing +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// RestartBuild represents the API handler to restart an existing build in the configured backend. +// RestartBuild represents the API handler to restart an existing build. func RestartBuild(c *gin.Context) { // capture middleware values m := c.MustGet("metadata").(*internal.Metadata) diff --git a/api/build/token.go b/api/build/token.go index fd0664684..d58a60bc5 100644 --- a/api/build/token.go +++ b/api/build/token.go @@ -30,13 +30,13 @@ import ( // - application/json // parameters: // - in: path -// name: repo -// description: Name of the repo +// name: org +// description: Name of the organization // required: true // type: string // - in: path -// name: org -// description: Name of the org +// name: repo +// description: Name of the repository // required: true // type: string // - in: path @@ -52,7 +52,11 @@ import ( // schema: // "$ref": "#/definitions/Token" // '400': -// description: Bad request +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '409': @@ -60,7 +64,7 @@ import ( // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to generate build token +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/build/update.go b/api/build/update.go index e1b64b423..e5e3385a0 100644 --- a/api/build/update.go +++ b/api/build/update.go @@ -23,7 +23,7 @@ import ( // swagger:operation PUT /api/v1/repos/{org}/{repo}/builds/{build} builds UpdateBuild // -// Updates a build in the configured backend +// Update a build // // --- // produces: @@ -31,22 +31,22 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path // name: build -// description: Build number to update +// description: Build number // required: true // type: integer // - in: body // name: body -// description: Payload containing the build to update +// description: The build object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Build" @@ -57,17 +57,25 @@ import ( // description: Successfully updated the build // schema: // "$ref": "#/definitions/Build" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '404': -// description: Unable to update the build +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the build +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // UpdateBuild represents the API handler to update -// a build for a repo in the configured backend. +// a build for a repo. func UpdateBuild(c *gin.Context) { // capture middleware values cl := claims.Retrieve(c) diff --git a/api/dashboard/create.go b/api/dashboard/create.go index f14a06fe1..38cb95115 100644 --- a/api/dashboard/create.go +++ b/api/dashboard/create.go @@ -20,7 +20,7 @@ import ( // swagger:operation POST /api/v1/dashboards dashboards CreateDashboard // -// Create a dashboard in the configured backend +// Create a dashboard // // --- // produces: @@ -28,7 +28,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing the dashboard to create +// description: Dashboard object to create // required: true // schema: // "$ref": "#/definitions/Dashboard" @@ -40,20 +40,20 @@ import ( // schema: // "$ref": "#/definitions/Dashboard" // '400': -// description: Bad request when creating dashboard +// description: Invalid request payload // schema: // "$ref": "#/definitions/Error" // '401': -// description: Unauthorized to create dashboard +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Server error when creating dashboard +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // CreateDashboard represents the API handler to -// create a dashboard in the configured backend. +// create a dashboard. func CreateDashboard(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/dashboard/delete.go b/api/dashboard/delete.go index a2798c940..bf921abe1 100644 --- a/api/dashboard/delete.go +++ b/api/dashboard/delete.go @@ -18,7 +18,7 @@ import ( // swagger:operation DELETE /api/v1/dashboards/{dashboard} dashboards DeleteDashboard // -// Delete a dashboard in the configured backend +// Delete a dashboard // // --- // produces: @@ -26,7 +26,7 @@ import ( // parameters: // - in: path // name: dashboard -// description: id of the dashboard +// description: Dashboard ID // required: true // type: string // security: @@ -36,21 +36,24 @@ import ( // description: Successfully deleted dashboard // schema: // type: string +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" // '401': -// description: Unauthorized to delete dashboard +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to find dashboard +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Server error when deleting dashboard +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// DeleteDashboard represents the API handler to remove -// a dashboard from the configured backend. +// DeleteDashboard represents the API handler to remove a dashboard. func DeleteDashboard(c *gin.Context) { // capture middleware values d := dashboard.Retrieve(c) diff --git a/api/dashboard/doc.go b/api/dashboard/doc.go new file mode 100644 index 000000000..eb9f60c2d --- /dev/null +++ b/api/dashboard/doc.go @@ -0,0 +1,8 @@ +// SPDX-License-Identifier: Apache-2.0 + +// Package dashboard provides the dashboard handlers for the Vela API. +// +// Usage: +// +// import "github.com/go-vela/server/api/dashboard" +package dashboard diff --git a/api/dashboard/get.go b/api/dashboard/get.go index 3535cb8b4..4cc34e93d 100644 --- a/api/dashboard/get.go +++ b/api/dashboard/get.go @@ -19,7 +19,7 @@ import ( // swagger:operation GET /api/v1/dashboards/{dashboard} dashboards GetDashboard // -// Get a dashboard in the configured backend +// Get a dashboard // // --- // produces: @@ -38,21 +38,25 @@ import ( // type: json // schema: // "$ref": "#/definitions/Dashboard" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" // '401': -// description: Unauthorized to retrieve dashboard +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to find dashboard +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Server error when retrieving dashboard +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// GetDashboard represents the API handler to capture -// a dashboard for a repo from the configured backend. +// GetDashboard represents the API handler to get +// a dashboard for a repository. func GetDashboard(c *gin.Context) { // capture middleware values d := dashboard.Retrieve(c) @@ -83,9 +87,9 @@ func GetDashboard(c *gin.Context) { c.JSON(http.StatusOK, dashboard) } -// buildRepoPartials is a helper function which takes the dashboard repo list and builds -// a list of RepoPartials with information about the associated repository and its latest -// five builds. +// buildRepoPartials is a helper function which takes the dashboard repo list +// and builds a list of RepoPartials with information about the associated +// repository and its latest five builds. func buildRepoPartials(c context.Context, repos []*types.DashboardRepo) ([]types.RepoPartial, error) { var result []types.RepoPartial diff --git a/api/dashboard/list_user.go b/api/dashboard/list_user.go index 656704358..c43a89f05 100644 --- a/api/dashboard/list_user.go +++ b/api/dashboard/list_user.go @@ -19,7 +19,7 @@ import ( // swagger:operation GET /api/v1/user/dashboards dashboards ListUserDashboards // -// Get all dashboards for the current user in the configured backend +// Get all dashboards for the current user // // --- // produces: @@ -33,20 +33,20 @@ import ( // schema: // "$ref": "#/definitions/Dashboard" // '400': -// description: Bad request to retrieve user dashboards +// description: Invalid request payload // schema: // "$ref": "#/definitions/Error" // '401': -// description: Unauthorized to retrieve user dashboards +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Server error when retrieving user dashboards +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // ListUserDashboards represents the API handler to capture a list -// of dashboards for a user from the configured backend. +// of dashboards for a user. func ListUserDashboards(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/dashboard/update.go b/api/dashboard/update.go index 7958ef72d..db11d4355 100644 --- a/api/dashboard/update.go +++ b/api/dashboard/update.go @@ -18,7 +18,7 @@ import ( // swagger:operation PUT /api/v1/dashboards/{dashboard} dashboards UpdateDashboard // -// Update a dashboard for the configured backend +// Update a dashboard // // --- // produces: @@ -31,7 +31,7 @@ import ( // type: string // - name: body // in: body -// description: Payload containing the dashboard to update +// description: The dashboard object with the fields to be updated // required: true // schema: // $ref: '#/definitions/Dashboard' @@ -43,24 +43,23 @@ import ( // schema: // "$ref": "#/definitions/Dashboard" // '400': -// description: Bad request when updating dashboard +// description: Invalid request payload or path // schema: // "$ref": "#/definitions/Error" // '401': -// description: Unauthorized to update dashboard +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to find dashboard +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Error while updating dashboard +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateDashboard represents the API handler to update -// a dashboard in the configured backend. +// UpdateDashboard represents the API handler to update a dashboard. func UpdateDashboard(c *gin.Context) { // capture middleware values d := dashboard.Retrieve(c) diff --git a/api/deployment/create.go b/api/deployment/create.go index b0fb02156..b596f75be 100644 --- a/api/deployment/create.go +++ b/api/deployment/create.go @@ -21,7 +21,7 @@ import ( // swagger:operation POST /api/v1/deployments/{org}/{repo} deployments CreateDeployment // -// Create a deployment for the configured backend +// Create a deployment // // --- // produces: @@ -29,12 +29,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // security: @@ -45,16 +45,24 @@ import ( // schema: // "$ref": "#/definitions/Deployment" // '400': -// description: Unable to create the deployment +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the deployment +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // CreateDeployment represents the API handler to -// create a deployment in the configured backend. +// create a deployment. func CreateDeployment(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/deployment/get.go b/api/deployment/get.go index c881bc800..8f890ab77 100644 --- a/api/deployment/get.go +++ b/api/deployment/get.go @@ -20,7 +20,7 @@ import ( // swagger:operation GET /api/v1/deployments/{org}/{repo}/{deployment} deployments GetDeployment // -// Get a deployment from the configured backend +// Get a deployment // // --- // produces: @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -49,16 +49,23 @@ import ( // schema: // "$ref": "#/definitions/Deployment" // '400': -// description: Unable to retrieve the deployment +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the deployment +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// GetDeployment represents the API handler to -// capture a deployment from the configured backend. +// GetDeployment represents the API handler to get a deployment. func GetDeployment(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/deployment/list.go b/api/deployment/list.go index 55667fdac..b07e3ba0a 100644 --- a/api/deployment/list.go +++ b/api/deployment/list.go @@ -20,7 +20,7 @@ import ( // swagger:operation GET /api/v1/deployments/{org}/{repo} deployments ListDeployments // -// Get a list of deployments for the configured backend +// Get all deployments for a repository // // --- // produces: @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: query @@ -61,19 +61,26 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the list of deployments +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the list of deployments +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListDeployments represents the API handler to capture -// a list of deployments from the configured backend. +// ListDeployments represents the API handler to get a list of deployments. func ListDeployments(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/health.go b/api/health.go index 71c8eacf4..12497408d 100644 --- a/api/health.go +++ b/api/health.go @@ -10,7 +10,7 @@ import ( // swagger:operation GET /health base Health // -// Check if the Vela API is available +// Check the Vela API health // // --- // produces: diff --git a/api/hook/create.go b/api/hook/create.go index a039371c5..bb8fbbaa0 100644 --- a/api/hook/create.go +++ b/api/hook/create.go @@ -20,28 +20,28 @@ import ( // swagger:operation POST /api/v1/hooks/{org}/{repo} webhook CreateHook // -// Create a webhook for the configured backend +// Create a hook // // --- // produces: // - application/json // parameters: -// - in: body -// name: body -// description: Webhook payload that we expect from the user or VCS -// required: true -// schema: -// "$ref": "#/definitions/Webhook" // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string +// - in: body +// name: body +// description: Hook object from the user or VCS to create +// required: true +// schema: +// "$ref": "#/definitions/Webhook" // security: // - ApiKeyAuth: [] // responses: @@ -50,16 +50,23 @@ import ( // schema: // "$ref": "#/definitions/Webhook" // '400': -// description: The webhook was unable to be created +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: The webhook was unable to be created +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// CreateHook represents the API handler to create -// a webhook in the configured backend. +// CreateHook represents the API handler to create a webhook. func CreateHook(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/hook/delete.go b/api/hook/delete.go index e31909a9f..f15f122df 100644 --- a/api/hook/delete.go +++ b/api/hook/delete.go @@ -19,7 +19,7 @@ import ( // swagger:operation DELETE /api/v1/hooks/{org}/{repo}/{hook} webhook DeleteHook // -// Delete a webhook for the configured backend +// Delete a hook // // --- // produces: @@ -27,12 +27,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -48,20 +48,23 @@ import ( // schema: // type: string // '400': -// description: The webhook was unable to be deleted +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: The webhook was unable to be deleted +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: The webhook was unable to be deleted +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// DeleteHook represents the API handler to remove -// a webhook from the configured backend. +// DeleteHook represents the API handler to remove a webhook. func DeleteHook(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/hook/doc.go b/api/hook/doc.go new file mode 100644 index 000000000..828826073 --- /dev/null +++ b/api/hook/doc.go @@ -0,0 +1,8 @@ +// SPDX-License-Identifier: Apache-2.0 + +// Package hook provides the hook handlers for the Vela API. +// +// Usage: +// +// import "github.com/go-vela/server/api/hook" +package hook diff --git a/api/hook/get.go b/api/hook/get.go index 849aa60f7..792a76a30 100644 --- a/api/hook/get.go +++ b/api/hook/get.go @@ -19,7 +19,7 @@ import ( // swagger:operation GET /api/v1/hooks/{org}/{repo}/{hook} webhook GetHook // -// Retrieve a webhook for the configured backend +// Get a hook // // --- // produces: @@ -27,12 +27,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -48,16 +48,23 @@ import ( // schema: // "$ref": "#/definitions/Webhook" // '400': -// description: Unable to retrieve the webhook +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the webhook +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// GetHook represents the API handler to capture a -// webhook from the configured backend. +// GetHook represents the API handler to get a hook. func GetHook(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/hook/list.go b/api/hook/list.go index e7235dba2..3f1b47851 100644 --- a/api/hook/list.go +++ b/api/hook/list.go @@ -20,7 +20,7 @@ import ( // swagger:operation GET /api/v1/hooks/{org}/{repo} webhook ListHooks // -// Retrieve the webhooks for the configured backend +// Get all hooks for a repository // // --- // produces: @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: query @@ -61,19 +61,27 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve webhooks +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve webhooks +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListHooks represents the API handler to capture a list -// of webhooks from the configured backend. +// ListHooks represents the API handler to get all hooks +// for a repository. func ListHooks(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/hook/redeliver.go b/api/hook/redeliver.go index a860c1718..f95c598b5 100644 --- a/api/hook/redeliver.go +++ b/api/hook/redeliver.go @@ -20,7 +20,7 @@ import ( // swagger:operation POST /api/v1/hooks/{org}/{repo}/{hook}/redeliver webhook RedeliverHook // -// Redeliver a webhook from the SCM +// Redeliver a hook // // --- // produces: @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -47,17 +47,21 @@ import ( // '200': // description: Successfully redelivered the webhook // schema: -// "$ref": "#/definitions/Webhook" +// type: string // '400': -// description: The webhook was unable to be redelivered +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: The webhook was unable to be redelivered +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: The webhook was unable to be redelivered +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/hook/update.go b/api/hook/update.go index 8d662b31c..35b2617a2 100644 --- a/api/hook/update.go +++ b/api/hook/update.go @@ -20,7 +20,7 @@ import ( // swagger:operation PUT /api/v1/hooks/{org}/{repo}/{hook} webhook UpdateHook // -// Update a webhook for the configured backend +// Update a hook // // --- // produces: @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -55,20 +55,23 @@ import ( // schema: // "$ref": "#/definitions/Webhook" // '400': -// description: The webhook was unable to be updated +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: The webhook was unable to be updated +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: The webhook was unable to be updated +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateHook represents the API handler to update -// a webhook in the configured backend. +// UpdateHook represents the API handler to update a hook. func UpdateHook(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/jwks.go b/api/jwks.go index 3d124f77d..4b0be0153 100644 --- a/api/jwks.go +++ b/api/jwks.go @@ -28,7 +28,7 @@ import ( // schema: // "$ref": "#/definitions/JWKSet" // '500': -// description: Unable to get the Vela JWKS +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/log/create_service.go b/api/log/create_service.go index 442714c27..275b86b64 100644 --- a/api/log/create_service.go +++ b/api/log/create_service.go @@ -31,12 +31,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -61,16 +61,24 @@ import ( // '201': // description: Successfully created the service logs // '400': -// description: Unable to create the service logs +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the service logs +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // CreateServiceLog represents the API handler to create -// the logs for a service in the configured backend. +// the logs for a service. func CreateServiceLog(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/log/create_step.go b/api/log/create_step.go index c5ed5f49f..42465299f 100644 --- a/api/log/create_step.go +++ b/api/log/create_step.go @@ -31,12 +31,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -61,16 +61,24 @@ import ( // '201': // description: Successfully created the logs for step // '400': -// description: Unable to create the logs for a step +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the logs for a step +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // CreateStepLog represents the API handler to create -// the logs for a step in the configured backend. +// the logs for a step. func CreateStepLog(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/log/delete_service.go b/api/log/delete_service.go index 9893d60d3..6c8b63c42 100644 --- a/api/log/delete_service.go +++ b/api/log/delete_service.go @@ -29,12 +29,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -54,13 +54,25 @@ import ( // description: Successfully deleted the service logs // schema: // type: string +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to delete the service logs +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // DeleteServiceLog represents the API handler to remove -// the logs for a service from the configured backend. +// the logs for a service. func DeleteServiceLog(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/log/delete_step.go b/api/log/delete_step.go index ebf505f1f..36ebfacff 100644 --- a/api/log/delete_step.go +++ b/api/log/delete_step.go @@ -29,12 +29,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -54,13 +54,25 @@ import ( // description: Successfully deleted the logs for the step // schema: // type: string +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to delete the logs for the step +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // DeleteStepLog represents the API handler to remove -// the logs for a step from the configured backend. +// the logs for a step. func DeleteStepLog(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/log/get_service.go b/api/log/get_service.go index 193850e90..c7c72fc73 100644 --- a/api/log/get_service.go +++ b/api/log/get_service.go @@ -21,7 +21,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/services/{service}/logs services GetServiceLog // -// Retrieve the logs for a service +// Get the logs for a service // // --- // produces: @@ -29,12 +29,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -54,13 +54,24 @@ import ( // description: Successfully retrieved the service logs // schema: // "$ref": "#/definitions/Log" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the service logs +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// GetServiceLog represents the API handler to capture -// the logs for a service from the configured backend. +// GetServiceLog represents the API handler to get the logs for a service. func GetServiceLog(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/log/get_step.go b/api/log/get_step.go index 2e8b524be..8e0a30223 100644 --- a/api/log/get_step.go +++ b/api/log/get_step.go @@ -21,7 +21,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/steps/{step}/logs steps GetStepLog // -// Retrieve the logs for a step +// Get the logs for a step // // --- // produces: @@ -29,12 +29,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -55,13 +55,24 @@ import ( // type: json // schema: // "$ref": "#/definitions/Log" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the logs for a step +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// GetStepLog represents the API handler to capture -// the logs for a step from the configured backend. +// GetStepLog represents the API handler to get the logs for a step. func GetStepLog(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/log/list_build.go b/api/log/list_build.go index 5fc996ef0..a33fd2c32 100644 --- a/api/log/list_build.go +++ b/api/log/list_build.go @@ -21,7 +21,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/logs builds ListLogsForBuild // -// List logs for a build in the configured backend +// Get all logs for a build // // --- // produces: @@ -29,12 +29,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -62,13 +62,24 @@ import ( // type: array // items: // "$ref": "#/definitions/Log" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve logs for the build +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListLogsForBuild represents the API handler to capture a -// list of logs for a build from the configured backend. +// ListLogsForBuild represents the API handler to get a list of logs for a build. func ListLogsForBuild(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/log/update_service.go b/api/log/update_service.go index 6d36b9bea..54e1fade8 100644 --- a/api/log/update_service.go +++ b/api/log/update_service.go @@ -22,7 +22,7 @@ import ( // swagger:operation PUT /api/v1/repos/{org}/{repo}/builds/{build}/services/{service}/logs services UpdateServiceLog // -// Update the logs for a service +// Update service logs for a build // // --- // deprecated: true @@ -31,12 +31,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -51,7 +51,7 @@ import ( // type: integer // - in: body // name: body -// description: Payload containing the log to update +// description: The log object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Log" @@ -60,19 +60,25 @@ import ( // responses: // '200': // description: Successfully updated the service logs -// schema: -// "$ref": "#/definitions/Log" // '400': -// description: Unable to updated the service logs +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to updates the service logs +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // UpdateServiceLog represents the API handler to update -// the logs for a service in the configured backend. +// the logs for a service. func UpdateServiceLog(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/log/update_step.go b/api/log/update_step.go index c34596a0f..4c27dd0ad 100644 --- a/api/log/update_step.go +++ b/api/log/update_step.go @@ -22,7 +22,7 @@ import ( // swagger:operation PUT /api/v1/repos/{org}/{repo}/builds/{build}/steps/{step}/logs steps UpdateStepLog // -// Update the logs for a step +// Update step logs for a build // // --- // deprecated: true @@ -31,12 +31,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -51,7 +51,7 @@ import ( // type: integer // - in: body // name: body -// description: Payload containing the log to update +// description: The log object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Log" @@ -60,19 +60,25 @@ import ( // responses: // '200': // description: Successfully updated the logs for step -// schema: -// "$ref": "#/definitions/Log" // '400': -// description: Unable to update the logs for a step +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the logs for a step +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // UpdateStepLog represents the API handler to update -// the logs for a step in the configured backend. +// the logs for a step. func UpdateStepLog(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/metrics.go b/api/metrics.go index 4a3323315..e23fa1d62 100644 --- a/api/metrics.go +++ b/api/metrics.go @@ -101,7 +101,7 @@ var ( // swagger:operation GET /metrics base BaseMetrics // -// Retrieve metrics from the Vela api +// Get Vela API metrics // // --- // produces: @@ -114,7 +114,7 @@ var ( // default: false // - in: query // name: repo_count -// description: Indicates a request for repo count +// description: Indicates a request for repository count // type: boolean // default: false // - in: query diff --git a/api/oi_config.go b/api/oi_config.go index 02edeb939..1111e352f 100644 --- a/api/oi_config.go +++ b/api/oi_config.go @@ -15,7 +15,7 @@ import ( // swagger:operation GET /_services/token/.well-known/openid-configuration token GetOpenIDConfig // -// Get the OpenID configuration for the Vela OIDC service +// Get the Vela OIDC service configuration // // --- // produces: diff --git a/api/pipeline/compile.go b/api/pipeline/compile.go index 4585451ba..67419d91d 100644 --- a/api/pipeline/compile.go +++ b/api/pipeline/compile.go @@ -22,21 +22,21 @@ import ( // swagger:operation POST /api/v1/pipelines/{org}/{repo}/{pipeline}/compile pipelines CompilePipeline // -// Get, expand and compile a pipeline from the configured backend +// Get, expand and compile a pipeline // // --- // produces: -// - application/x-yaml +// - application/yaml // - application/json // parameters: // - in: path -// name: repo -// description: Name of the repo +// name: org +// description: Name of the organization // required: true // type: string // - in: path -// name: org -// description: Name of the org +// name: repo +// description: Name of the repository // required: true // type: string // - in: path @@ -60,11 +60,19 @@ import ( // schema: // "$ref": "#/definitions/PipelineBuild" // '400': -// description: Unable to validate the pipeline configuration +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve the pipeline configuration +// description: Not found +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/pipeline/create.go b/api/pipeline/create.go index 1092a4051..1420fdc67 100644 --- a/api/pipeline/create.go +++ b/api/pipeline/create.go @@ -19,7 +19,7 @@ import ( // swagger:operation POST /api/v1/pipelines/{org}/{repo} pipelines CreatePipeline // -// Create a pipeline in the configured backend +// Create a pipeline // // --- // produces: @@ -27,17 +27,17 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: body // name: body -// description: Payload containing the pipeline to create +// description: Pipeline object to create // required: true // schema: // "$ref": "#/definitions/Pipeline" @@ -50,20 +50,24 @@ import ( // schema: // "$ref": "#/definitions/Pipeline" // '400': -// description: Unable to create the pipeline +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to create the pipeline +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the pipeline +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // CreatePipeline represents the API handler to -// create a pipeline in the configured backend. +// create a pipeline. func CreatePipeline(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/pipeline/delete.go b/api/pipeline/delete.go index b59f1adc3..89c0f362c 100644 --- a/api/pipeline/delete.go +++ b/api/pipeline/delete.go @@ -19,7 +19,7 @@ import ( // swagger:operation DELETE /api/v1/pipelines/{org}/{repo}/{pipeline} pipelines DeletePipeline // -// Delete a pipeline from the configured backend +// Delete a pipeline // // --- // produces: @@ -27,12 +27,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -48,16 +48,23 @@ import ( // schema: // type: string // '400': -// description: Unable to delete the pipeline +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to delete the pipeline +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// DeletePipeline represents the API handler to remove -// a pipeline for a repo from the configured backend. +// DeletePipeline represents the API handler to remove a pipeline for a repository. func DeletePipeline(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/pipeline/expand.go b/api/pipeline/expand.go index 17e62181c..062992a81 100644 --- a/api/pipeline/expand.go +++ b/api/pipeline/expand.go @@ -21,21 +21,21 @@ import ( // swagger:operation POST /api/v1/pipelines/{org}/{repo}/{pipeline}/expand pipelines ExpandPipeline // -// Get and expand a pipeline from the configured backend +// Expand a pipeline // // --- // produces: -// - application/x-yaml +// - application/yaml // - application/json // parameters: // - in: path -// name: repo -// description: Name of the repo +// name: org +// description: Name of the organization // required: true // type: string // - in: path -// name: org -// description: Name of the org +// name: repo +// description: Name of the repository // required: true // type: string // - in: path @@ -60,11 +60,19 @@ import ( // schema: // "$ref": "#/definitions/PipelineBuild" // '400': -// description: Unable to expand the pipeline configuration +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve the pipeline configuration +// description: Not found +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/pipeline/get.go b/api/pipeline/get.go index 69739f523..d6fdcbeed 100644 --- a/api/pipeline/get.go +++ b/api/pipeline/get.go @@ -16,7 +16,7 @@ import ( // swagger:operation GET /api/v1/pipelines/{org}/{repo}/{pipeline} pipelines GetPipeline // -// Get a pipeline from the configured backend +// Get a pipeline // // --- // produces: @@ -24,12 +24,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -45,9 +45,24 @@ import ( // type: json // schema: // "$ref": "#/definitions/Pipeline" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error +// schema: +// "$ref": "#/definitions/Error" -// GetPipeline represents the API handler to capture -// a pipeline for a repo from the configured backend. +// GetPipeline represents the API handler to get a pipeline for a repo. func GetPipeline(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/pipeline/list.go b/api/pipeline/list.go index 0ffdcff95..c2fd7f0b6 100644 --- a/api/pipeline/list.go +++ b/api/pipeline/list.go @@ -20,7 +20,7 @@ import ( // swagger:operation GET /api/v1/pipelines/{org}/{repo} pipelines ListPipelines // -// List pipelines from the configured backend +// Get all pipelines for a repository // // --- // produces: @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: query @@ -61,19 +61,27 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the list of pipelines +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the list of pipelines +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListPipelines represents the API handler to capture a list -// of pipelines for a repo from the configured backend. +// ListPipelines represents the API handler to get a list +// of pipelines for a repository. func ListPipelines(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/pipeline/template.go b/api/pipeline/template.go index 66c8cd627..8271732b6 100644 --- a/api/pipeline/template.go +++ b/api/pipeline/template.go @@ -25,21 +25,21 @@ import ( // swagger:operation GET /api/v1/pipelines/{org}/{repo}/{pipeline}/templates pipelines GetTemplates // -// Get a map of templates utilized by a pipeline from the configured backend +// Get pipeline templates // // --- // produces: -// - application/x-yaml +// - application/yaml // - application/json // parameters: // - in: path -// name: repo -// description: Name of the repo +// name: org +// description: Name of the organization // required: true // type: string // - in: path -// name: org -// description: Name of the org +// name: repo +// description: Name of the repository // required: true // type: string // - in: path @@ -61,13 +61,23 @@ import ( // '200': // description: Successfully retrieved the map of pipeline templates // schema: -// "$ref": "#/definitions/Template" +// type: array +// items: +// "$ref": "#/definitions/Template" // '400': -// description: Unable to retrieve the pipeline configuration templates +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve the pipeline configuration templates +// description: Not found +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/pipeline/update.go b/api/pipeline/update.go index f5230fbe8..bc70d53c4 100644 --- a/api/pipeline/update.go +++ b/api/pipeline/update.go @@ -20,7 +20,7 @@ import ( // swagger:operation PUT /api/v1/pipelines/{org}/{repo}/{pipeline} pipelines UpdatePipeline // -// Update a pipeline in the configured backend +// Update a pipeline // // --- // produces: @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -43,7 +43,7 @@ import ( // type: string // - in: body // name: body -// description: Payload containing the pipeline to update +// description: The pipeline object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Pipeline" @@ -54,17 +54,25 @@ import ( // description: Successfully updated the pipeline // schema: // "$ref": "#/definitions/Pipeline" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '404': -// description: Unable to update the pipeline +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the pipeline +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // UpdatePipeline represents the API handler to update -// a pipeline for a repo in the configured backend. +// a pipeline for a repo. func UpdatePipeline(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/pipeline/validate.go b/api/pipeline/validate.go index b7f43664d..335f61850 100644 --- a/api/pipeline/validate.go +++ b/api/pipeline/validate.go @@ -20,21 +20,21 @@ import ( // swagger:operation POST /api/v1/pipelines/{org}/{repo}/{pipeline}/validate pipelines ValidatePipeline // -// Get, expand and validate a pipeline from the configured backend +// Get, expand and validate a pipeline // // --- // produces: -// - application/x-yaml +// - application/yaml // - application/json // parameters: // - in: path -// name: repo -// description: Name of the repo +// name: org +// description: Name of the organization // required: true // type: string // - in: path -// name: org -// description: Name of the org +// name: repo +// description: Name of the repository // required: true // type: string // - in: path @@ -58,11 +58,19 @@ import ( // schema: // type: string // '400': -// description: Unable to validate the pipeline configuration +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve the pipeline configuration +// description: Not found +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/queue/doc.go b/api/queue/doc.go new file mode 100644 index 000000000..e794792cf --- /dev/null +++ b/api/queue/doc.go @@ -0,0 +1,8 @@ +// SPDX-License-Identifier: Apache-2.0 + +// Package queue provides the queue handlers for the Vela API. +// +// Usage: +// +// import "github.com/go-vela/server/api/queue" +package queue diff --git a/api/repo/chown.go b/api/repo/chown.go index f68a4fac6..30442c683 100644 --- a/api/repo/chown.go +++ b/api/repo/chown.go @@ -18,7 +18,7 @@ import ( // swagger:operation PATCH /api/v1/repos/{org}/{repo}/chown repos ChownRepo // -// Change the owner of the webhook for a repo +// Change the owner of a repository // // --- // produces: @@ -26,28 +26,40 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // security: // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully changed the owner for the repo +// description: Successfully changed the owner for the repository // schema: // type: string +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to change the owner for the repo +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // ChownRepo represents the API handler to change -// the owner of a repo in the configured backend. +// the owner of a repo. func ChownRepo(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/repo/create.go b/api/repo/create.go index 7249bbfa4..7516b9682 100644 --- a/api/repo/create.go +++ b/api/repo/create.go @@ -25,7 +25,7 @@ import ( // swagger:operation POST /api/v1/repos repos CreateRepo // -// Create a repo in the configured backend +// Create a repository // // --- // produces: @@ -33,7 +33,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing the repo to create +// description: Repo object to create // required: true // schema: // "$ref": "#/definitions/Repo" @@ -45,7 +45,11 @@ import ( // schema: // "$ref": "#/definitions/Repo" // '400': -// description: Unable to create the repo +// description: Invalid request payload +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '403': @@ -57,7 +61,7 @@ import ( // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the repo +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // '503': @@ -65,8 +69,7 @@ import ( // schema: // "$ref": "#/definitions/Error" -// CreateRepo represents the API handler to -// create a repo in the configured backend. +// CreateRepo represents the API handler to create a repository. // //nolint:funlen,gocyclo // ignore function length and cyclomatic complexity func CreateRepo(c *gin.Context) { diff --git a/api/repo/delete.go b/api/repo/delete.go index 7a70ceac4..c75d2fc51 100644 --- a/api/repo/delete.go +++ b/api/repo/delete.go @@ -19,7 +19,7 @@ import ( // swagger:operation DELETE /api/v1/repos/{org}/{repo} repos DeleteRepo // -// Delete a repo in the configured backend +// Delete a repository // // --- // produces: @@ -27,12 +27,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // security: @@ -42,17 +42,24 @@ import ( // description: Successfully deleted the repo // schema: // type: string -// '500': -// description: Unable to deleted the repo +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" -// '510': -// description: Unable to deleted the repo +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// DeleteRepo represents the API handler to remove -// a repo from the configured backend. +// DeleteRepo represents the API handler to remove a repository. func DeleteRepo(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/repo/get.go b/api/repo/get.go index 61df846d4..ac988093c 100644 --- a/api/repo/get.go +++ b/api/repo/get.go @@ -15,7 +15,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo} repos GetRepo // -// Get a repo in the configured backend +// Get a repository // // --- // produces: @@ -23,12 +23,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // security: @@ -38,9 +38,20 @@ import ( // description: Successfully retrieved the repo // schema: // "$ref": "#/definitions/Repo" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Repo" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Repo" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Repo" -// GetRepo represents the API handler to -// capture a repo from the configured backend. +// GetRepo represents the API handler to get a repository. func GetRepo(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/repo/list.go b/api/repo/list.go index 010ae0cfe..306214605 100644 --- a/api/repo/list.go +++ b/api/repo/list.go @@ -18,7 +18,7 @@ import ( // swagger:operation GET /api/v1/repos repos ListRepos // -// Get all repos in the configured backend +// Get all repositories // // --- // produces: @@ -49,19 +49,23 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the repo +// description: Invalid request payload +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the repo +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListRepos represents the API handler to capture a list -// of repos for a user from the configured backend. +// ListRepos represents the API handler to get a list +// of repositories for a user. func ListRepos(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/repo/list_org.go b/api/repo/list_org.go index 565082f97..2466efce1 100644 --- a/api/repo/list_org.go +++ b/api/repo/list_org.go @@ -21,7 +21,7 @@ import ( // swagger:operation GET /api/v1/repos/{org} repos ListReposForOrg // -// Get all repos for the provided org in the configured backend +// Get all repositories for an organization // // --- // produces: @@ -31,7 +31,7 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: query @@ -70,19 +70,23 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the org +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the org +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListReposForOrg represents the API handler to capture a list -// of repos for an org from the configured backend. +// ListReposForOrg represents the API handler to get a list +// of repositories for an organization. func ListReposForOrg(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/repo/repair.go b/api/repo/repair.go index 1e3eefb33..af43148e7 100644 --- a/api/repo/repair.go +++ b/api/repo/repair.go @@ -21,7 +21,7 @@ import ( // swagger:operation PATCH /api/v1/repos/{org}/{repo}/repair repos RepairRepo // -// Remove and recreate the webhook for a repo +// Repair a hook for a repository in Vela and the configured SCM // // --- // produces: @@ -29,12 +29,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // security: @@ -44,8 +44,20 @@ import ( // description: Successfully repaired the repo // schema: // type: string +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to repair the repo +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/repo/update.go b/api/repo/update.go index 82fd02922..4626dd72b 100644 --- a/api/repo/update.go +++ b/api/repo/update.go @@ -24,7 +24,7 @@ import ( // swagger:operation PUT /api/v1/repos/{org}/{repo} repos UpdateRepo // -// Update a repo in the configured backend +// Update a repository // // --- // produces: @@ -32,17 +32,17 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: body // name: body -// description: Payload containing the repo to update +// description: The repository object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Repo" @@ -54,11 +54,15 @@ import ( // schema: // "$ref": "#/definitions/Repo" // '400': -// description: Unable to update the repo +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the repo +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // '503': @@ -66,8 +70,7 @@ import ( // schema: // "$ref": "#/definitions/Error" -// UpdateRepo represents the API handler to update -// a repo in the configured backend. +// UpdateRepo represents the API handler to update a repo. // //nolint:funlen,gocyclo // ignore function length func UpdateRepo(c *gin.Context) { diff --git a/api/schedule/create.go b/api/schedule/create.go index a63d60fa4..938c31e1f 100644 --- a/api/schedule/create.go +++ b/api/schedule/create.go @@ -21,7 +21,7 @@ import ( // swagger:operation POST /api/v1/schedules/{org}/{repo} schedules CreateSchedule // -// Create a schedule in the configured backend +// Create a schedule // // --- // produces: @@ -29,17 +29,17 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: body // name: body -// description: Payload containing the schedule to create +// description: Schedule object to create // required: true // schema: // "$ref": "#/definitions/Schedule" @@ -51,19 +51,27 @@ import ( // schema: // "$ref": "#/definitions/Schedule" // '400': -// description: Unable to create the schedule +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '403': // description: Unable to create the schedule // schema: // "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '409': // description: Unable to create the schedule // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the schedule +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // '503': @@ -72,7 +80,7 @@ import ( // "$ref": "#/definitions/Error" // CreateSchedule represents the API handler to -// create a schedule in the configured backend. +// create a schedule. func CreateSchedule(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/schedule/delete.go b/api/schedule/delete.go index 73c60a8c0..19c448aa1 100644 --- a/api/schedule/delete.go +++ b/api/schedule/delete.go @@ -19,7 +19,7 @@ import ( // swagger:operation DELETE /api/v1/repos/{org}/{repo}/{schedule} schedules DeleteSchedule // -// Delete a schedule in the configured backend +// Delete a schedule // // --- // produces: @@ -27,12 +27,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -47,17 +47,24 @@ import ( // description: Successfully deleted the schedule // schema: // type: string -// '500': -// description: Unable to delete the schedule +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" -// '510': -// description: Unable to delete the schedule +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// DeleteSchedule represents the API handler to remove -// a schedule from the configured backend. +// DeleteSchedule represents the API handler to remove a schedule. func DeleteSchedule(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/schedule/doc.go b/api/schedule/doc.go new file mode 100644 index 000000000..c6736d529 --- /dev/null +++ b/api/schedule/doc.go @@ -0,0 +1,8 @@ +// SPDX-License-Identifier: Apache-2.0 + +// Package schedule provides the schedule handlers for the Vela API. +// +// Usage: +// +// import "github.com/go-vela/server/api/schedule" +package schedule diff --git a/api/schedule/get.go b/api/schedule/get.go index d9ff954b2..2978860b9 100644 --- a/api/schedule/get.go +++ b/api/schedule/get.go @@ -16,7 +16,7 @@ import ( // swagger:operation GET /api/v1/schedules/{org}/{repo}/{schedule} schedules GetSchedule // -// Get a schedule in the configured backend +// Get a schedule // // --- // produces: @@ -24,12 +24,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -44,9 +44,20 @@ import ( // description: Successfully retrieved the schedule // schema: // "$ref": "#/definitions/Schedule" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" -// GetSchedule represents the API handler to -// capture a schedule from the configured backend. +// GetSchedule represents the API handler to get a schedule. func GetSchedule(c *gin.Context) { // capture middleware values o := org.Retrieve(c) diff --git a/api/schedule/list.go b/api/schedule/list.go index c6c424647..a42569ba0 100644 --- a/api/schedule/list.go +++ b/api/schedule/list.go @@ -18,7 +18,7 @@ import ( // swagger:operation GET /api/v1/schedules/{org}/{repo} schedules ListSchedules // -// Get all schedules in the configured backend +// Get all schedules for a repository // // --- // produces: @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: query @@ -59,19 +59,26 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the schedules +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the schedules +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListSchedules represents the API handler to capture a list -// of schedules for a repo from the configured backend. +// ListSchedules represents the API handler to get a list of schedules for a repository. func ListSchedules(c *gin.Context) { // capture middleware values r := repo.Retrieve(c) diff --git a/api/schedule/update.go b/api/schedule/update.go index c29678570..149cd3e74 100644 --- a/api/schedule/update.go +++ b/api/schedule/update.go @@ -20,7 +20,7 @@ import ( // swagger:operation PUT /api/v1/schedules/{org}/{repo}/{schedule} schedules UpdateSchedule // -// Update a schedule for the configured backend +// Update a schedule // // --- // produces: @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -43,7 +43,7 @@ import ( // type: string // - in: body // name: body -// description: Payload containing the schedule to update +// description: The schedule object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Schedule" @@ -55,20 +55,23 @@ import ( // schema: // "$ref": "#/definitions/Schedule" // '400': -// description: Unable to update the schedule +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to update the schedule +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the schedule +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateSchedule represents the API handler to update -// a schedule in the configured backend. +// UpdateSchedule represents the API handler to update a schedule. func UpdateSchedule(c *gin.Context) { // capture middleware values r := repo.Retrieve(c) diff --git a/api/scm/sync.go b/api/scm/sync.go index 9520fb143..66e2e6fd2 100644 --- a/api/scm/sync.go +++ b/api/scm/sync.go @@ -20,7 +20,7 @@ import ( // swagger:operation PATCH /api/v1/scm/repos/{org}/{repo}/sync scm SyncRepo // -// Sync up scm service and database in the context of a specific repo +// Sync a repository with the scm service // // --- // produces: @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // security: @@ -46,15 +46,23 @@ import ( // '204': // description: Successful request resulting in no change // '301': -// description: Repo has moved permanently +// description: Repo has moved permanently (from SCM) +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '403': -// description: User has been forbidden access to repository +// description: User has been forbidden access to repository (from SCM) +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to synchronize repo +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" @@ -83,7 +91,6 @@ func SyncRepo(c *gin.Context) { // retrieve repo from source code manager service _, respCode, err := scm.FromContext(c).GetRepo(ctx, u, r) - // if there is an error retrieving repo, we know it is deleted: set to inactive if err != nil { if respCode == http.StatusNotFound { diff --git a/api/scm/sync_org.go b/api/scm/sync_org.go index b1162503c..8809e7b4f 100644 --- a/api/scm/sync_org.go +++ b/api/scm/sync_org.go @@ -19,7 +19,7 @@ import ( // swagger:operation PATCH /api/v1/scm/orgs/{org}/sync scm SyncReposForOrg // -// Sync up repos from scm service and database in a specified org +// Sync repositories from scm service and database in a specified organization // // --- // produces: @@ -27,7 +27,7 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // security: @@ -42,15 +42,23 @@ import ( // '204': // description: Successful request resulting in no change // '301': -// description: One repo in the org has moved permanently +// description: One repository in the organiation has moved permanently (from SCM) +// schema: +// "$ref": "#/definitions/Error" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '403': -// description: User has been forbidden access to at least one repository in org +// description: User has been forbidden access to at least one repository in organiation (from SCM) // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to synchronize org repositories +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/secret/create.go b/api/secret/create.go index fd44f1779..e2d3e2c50 100644 --- a/api/secret/create.go +++ b/api/secret/create.go @@ -45,17 +45,17 @@ import ( // type: string // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: name -// description: Name of the repo if a repo secret, team name if a shared secret, or '*' if an org secret +// description: Name of the repository if a repository secret, team name if a shared secret, or '*' if an organization secret // required: true // type: string // - in: body // name: body -// description: Payload containing the secret to create +// description: Secret object to create // required: true // schema: // "$ref": "#/definitions/Secret" @@ -67,16 +67,20 @@ import ( // schema: // "$ref": "#/definitions/Secret" // '400': -// description: Unable to create the secret +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the secret +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // CreateSecret represents the API handler to -// create a secret in the configured backend. +// create a secret. // //nolint:funlen // suppress long function error func CreateSecret(c *gin.Context) { diff --git a/api/secret/delete.go b/api/secret/delete.go index dd4db4145..188016155 100644 --- a/api/secret/delete.go +++ b/api/secret/delete.go @@ -19,7 +19,7 @@ import ( // // swagger:operation DELETE /api/v1/secrets/{engine}/{type}/{org}/{name}/{secret} secrets DeleteSecret // -// Delete a secret from the configured backend +// Delete a secret // // --- // produces: @@ -41,12 +41,12 @@ import ( // type: string // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: name -// description: Name of the repo if a repo secret, team name if a shared secret, or '*' if an org secret +// description: Name of the repository if a repository secret, team name if a shared secret, or '*' if an organzation secret // required: true // type: string // - in: path @@ -61,8 +61,12 @@ import ( // description: Successfully deleted the secret // schema: // type: string +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to delete the secret +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/secret/get.go b/api/secret/get.go index 44c379f8b..dc4d4da1f 100644 --- a/api/secret/get.go +++ b/api/secret/get.go @@ -20,7 +20,7 @@ import ( // // swagger:operation GET /api/v1/secrets/{engine}/{type}/{org}/{name}/{secret} secrets GetSecret // -// Retrieve a secret from the configured backend +// Get a secret // // --- // produces: @@ -42,12 +42,12 @@ import ( // type: string // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: name -// description: Name of the repo if a repo secret, team name if a shared secret, or '*' if an org secret +// description: Name of the repository if a repository secret, team name if a shared secret, or '*' if an organization secret // required: true // type: string // - in: path @@ -62,8 +62,12 @@ import ( // description: Successfully retrieved the secret // schema: // "$ref": "#/definitions/Secret" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the secret +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/secret/list.go b/api/secret/list.go index c142b89a6..a6699ef34 100644 --- a/api/secret/list.go +++ b/api/secret/list.go @@ -23,7 +23,7 @@ import ( // // swagger:operation GET /api/v1/secrets/{engine}/{type}/{org}/{name} secrets ListSecrets // -// Retrieve a list of secrets from the configured backend +// Get all organization or shared secrets // // --- // produces: @@ -45,12 +45,12 @@ import ( // type: string // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: name -// description: Name of the repo if a repo secret, team name if a shared secret, or '*' if an org secret +// description: Name of the repository if a repository secret, team name if a shared secret, or '*' if an organization secret // required: true // type: string // - in: query @@ -78,19 +78,22 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the list of secrets +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the list of secrets +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListSecrets represents the API handler to capture -// a list of secrets from the configured backend. +// ListSecrets represents the API handler to get a list of secrets. func ListSecrets(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/secret/update.go b/api/secret/update.go index cb012c719..dc66df7ce 100644 --- a/api/secret/update.go +++ b/api/secret/update.go @@ -21,7 +21,7 @@ import ( // // swagger:operation PUT /api/v1/secrets/{engine}/{type}/{org}/{name}/{secret} secrets UpdateSecret // -// Update a secret on the configured backend +// Update a secret // // --- // produces: @@ -43,12 +43,12 @@ import ( // type: string // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: name -// description: Name of the repo if a repo secret, team name if a shared secret, or '*' if an org secret +// description: Name of the repository if a repository secret, team name if a shared secret, or '*' if an organization secret // required: true // type: string // - in: path @@ -70,11 +70,15 @@ import ( // schema: // "$ref": "#/definitions/Secret" // '400': -// description: Unable to update the secret +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the secret +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/service/create.go b/api/service/create.go index 2ccb9e314..e4289cc0b 100644 --- a/api/service/create.go +++ b/api/service/create.go @@ -22,7 +22,7 @@ import ( // swagger:operation POST /api/v1/repos/{org}/{repo}/builds/{build}/services services CreateService // -// Create a service for a build in the configured backend +// Create a service for a build // // --- // produces: @@ -30,12 +30,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -45,7 +45,7 @@ import ( // type: integer // - in: body // name: body -// description: Payload containing the service to create +// description: Service object to create // required: true // schema: // "$ref": "#/definitions/Service" @@ -57,16 +57,24 @@ import ( // schema: // "$ref": "#/definitions/Service" // '400': -// description: Unable to create the service +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the service +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // CreateService represents the API handler to create -// a service for a build in the configured backend. +// a service for a build. func CreateService(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/service/delete.go b/api/service/delete.go index 915804a27..90ca9b9b6 100644 --- a/api/service/delete.go +++ b/api/service/delete.go @@ -21,7 +21,7 @@ import ( // // swagger:operation DELETE /api/v1/repos/{org}/{repo}/builds/{build}/services/{service} services DeleteService // -// Delete a service for a build in the configured backend +// Delete a service for a build // // --- // produces: @@ -29,12 +29,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -54,13 +54,24 @@ import ( // description: Successfully deleted the service // schema: // type: string +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to delete the service +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// DeleteService represents the API handler to remove -// a service for a build from the configured backend. +// DeleteService represents the API handler to remove a service for a build. func DeleteService(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/service/get.go b/api/service/get.go index b81b69735..c54d1427d 100644 --- a/api/service/get.go +++ b/api/service/get.go @@ -18,7 +18,7 @@ import ( // // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/services/{service} services GetService // -// Get a service for a build in the configured backend +// Get a service for a build // // --- // produces: @@ -26,12 +26,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -52,16 +52,23 @@ import ( // schema: // "$ref": "#/definitions/Service" // '400': -// description: Unable to retrieve the service +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the service +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// GetService represents the API handler to capture a -// service for a build from the configured backend. +// GetService represents the API handler to get a service for a build. func GetService(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/service/list.go b/api/service/list.go index 6697a7282..2862a28d4 100644 --- a/api/service/list.go +++ b/api/service/list.go @@ -21,7 +21,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/services services ListServices // -// Get a list of all services for a build in the configured backend +// Get all services for a build // // --- // produces: @@ -29,12 +29,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -67,19 +67,26 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the list of services +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the list of services +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListServices represents the API handler to capture a list -// of services for a build from the configured backend. +// ListServices represents the API handler to get a list of services for a build. func ListServices(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/service/plan.go b/api/service/plan.go index 05673f05e..faed795cb 100644 --- a/api/service/plan.go +++ b/api/service/plan.go @@ -16,7 +16,7 @@ import ( // PlanServices is a helper function to plan all services // in the build for execution. This creates the services -// for the build in the configured backend. +// for the build. func PlanServices(ctx context.Context, database database.Interface, p *pipeline.Build, b *types.Build) ([]*library.Service, error) { // variable to store planned services services := []*library.Service{} diff --git a/api/service/update.go b/api/service/update.go index a539270e3..0b2825997 100644 --- a/api/service/update.go +++ b/api/service/update.go @@ -22,7 +22,7 @@ import ( // // swagger:operation PUT /api/v1/repos/{org}/{repo}/builds/{build}/services/{service} services UpdateService // -// Update a service for a build in the configured backend +// Update a service for a build // // --- // produces: @@ -30,12 +30,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -50,7 +50,7 @@ import ( // type: integer // - in: body // name: body -// description: Payload containing the service to update +// description: The service object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Service" @@ -62,16 +62,24 @@ import ( // schema: // "$ref": "#/definitions/Service" // '400': -// description: Unable to update the service +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the service +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // UpdateService represents the API handler to update -// a service for a build in the configured backend. +// a service for a build. func UpdateService(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/step/create.go b/api/step/create.go index 2218d214d..33225a93f 100644 --- a/api/step/create.go +++ b/api/step/create.go @@ -30,12 +30,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -45,7 +45,7 @@ import ( // type: integer // - in: body // name: body -// description: Payload containing the step to create +// description: Step object to create // required: true // schema: // "$ref": "#/definitions/Step" @@ -57,16 +57,24 @@ import ( // schema: // "$ref": "#/definitions/Step" // '400': -// description: Unable to create the step +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the step +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // CreateStep represents the API handler to create -// a step for a build in the configured backend. +// a step for a build. func CreateStep(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/step/delete.go b/api/step/delete.go index 8d735717a..27a3eff1d 100644 --- a/api/step/delete.go +++ b/api/step/delete.go @@ -28,12 +28,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -53,13 +53,24 @@ import ( // description: Successfully deleted the step // schema: // type: string +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Successfully deleted the step +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// DeleteStep represents the API handler to remove -// a step for a build from the configured backend. +// DeleteStep represents the API handler to remove a step for a build. func DeleteStep(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/step/get.go b/api/step/get.go index 9582b5928..09267ffb3 100644 --- a/api/step/get.go +++ b/api/step/get.go @@ -17,7 +17,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/steps/{step} steps GetStep // -// Retrieve a step for a build +// Get a step for a build // // --- // produces: @@ -25,12 +25,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -50,9 +50,20 @@ import ( // description: Successfully retrieved the step // schema: // "$ref": "#/definitions/Step" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" -// GetStep represents the API handler to capture a -// step for a build from the configured backend. +// GetStep represents the API handler to get a step for a build. func GetStep(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/step/list.go b/api/step/list.go index 603d7083b..67617b2b6 100644 --- a/api/step/list.go +++ b/api/step/list.go @@ -21,7 +21,7 @@ import ( // swagger:operation GET /api/v1/repos/{org}/{repo}/builds/{build}/steps steps ListSteps // -// Retrieve a list of steps for a build +// Get all steps for a build // // --- // produces: @@ -29,12 +29,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -67,19 +67,26 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the list of steps +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the list of steps +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListSteps represents the API handler to capture a list -// of steps for a build from the configured backend. +// ListSteps represents the API handler to get a list of steps for a build. func ListSteps(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/step/plan.go b/api/step/plan.go index f685170a3..6b3faac06 100644 --- a/api/step/plan.go +++ b/api/step/plan.go @@ -19,7 +19,7 @@ import ( // PlanSteps is a helper function to plan all steps // in the build for execution. This creates the steps -// for the build in the configured backend. +// for the build. func PlanSteps(ctx context.Context, database database.Interface, scm scm.Service, p *pipeline.Build, b *types.Build) ([]*library.Step, error) { // variable to store planned steps steps := []*library.Step{} diff --git a/api/step/update.go b/api/step/update.go index cb767de4e..87e2fc6dd 100644 --- a/api/step/update.go +++ b/api/step/update.go @@ -31,12 +31,12 @@ import ( // parameters: // - in: path // name: org -// description: Name of the org +// description: Name of the organization // required: true // type: string // - in: path // name: repo -// description: Name of the repo +// description: Name of the repository // required: true // type: string // - in: path @@ -51,7 +51,7 @@ import ( // type: integer // - in: body // name: body -// description: Payload containing the step to update +// description: The step object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Step" @@ -63,16 +63,24 @@ import ( // schema: // "$ref": "#/definitions/Step" // '400': -// description: Unable to update the step +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the step +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // UpdateStep represents the API handler to update -// a step for a build in the configured backend. +// a step for a build. func UpdateStep(c *gin.Context) { // capture middleware values b := build.Retrieve(c) diff --git a/api/user/create.go b/api/user/create.go index cd68556bf..bf37a8472 100644 --- a/api/user/create.go +++ b/api/user/create.go @@ -17,7 +17,7 @@ import ( // swagger:operation POST /api/v1/users users CreateUser // -// Create a user for the configured backend +// Create a user // // --- // produces: @@ -25,7 +25,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing the user to create +// description: User object to create // required: true // schema: // "$ref": "#/definitions/User" @@ -37,16 +37,19 @@ import ( // schema: // "$ref": "#/definitions/User" // '400': -// description: Unable to create the user +// description: Invalid request payload +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the user +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// CreateUser represents the API handler to create -// a user in the configured backend. +// CreateUser represents the API handler to create a user. func CreateUser(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/user/create_token.go b/api/user/create_token.go index e1b8fa9c0..6a3bb2678 100644 --- a/api/user/create_token.go +++ b/api/user/create_token.go @@ -31,13 +31,17 @@ import ( // description: Successfully created a token for the current user // schema: // "$ref": "#/definitions/Token" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '503': // description: Unable to create a token for the current user // schema: // "$ref": "#/definitions/Error" // CreateToken represents the API handler to create -// a user token in the configured backend. +// a user token. func CreateToken(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/user/delete.go b/api/user/delete.go index fd32d75d0..35c026736 100644 --- a/api/user/delete.go +++ b/api/user/delete.go @@ -16,7 +16,7 @@ import ( // swagger:operation DELETE /api/v1/users/{user} users DeleteUser // -// Delete a user for the configured backend +// Delete a user // // --- // produces: @@ -31,20 +31,23 @@ import ( // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully deleted of user +// description: Successfully deleted user // schema: // type: string +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '404': -// description: Unable to delete user +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to delete user +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// DeleteUser represents the API handler to remove -// a user from the configured backend. +// DeleteUser represents the API handler to remove a user. func DeleteUser(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/user/delete_token.go b/api/user/delete_token.go index b0caa2ac1..1f21a7a24 100644 --- a/api/user/delete_token.go +++ b/api/user/delete_token.go @@ -31,13 +31,17 @@ import ( // description: Successfully delete a token for the current user // schema: // type: string -// '500': +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '503': // description: Unable to delete a token for the current user // schema: // "$ref": "#/definitions/Error" // DeleteToken represents the API handler to revoke -// and recreate a user token in the configured backend. +// and recreate a user token. func DeleteToken(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/user/get.go b/api/user/get.go index 488cd9705..708eb56bb 100644 --- a/api/user/get.go +++ b/api/user/get.go @@ -16,7 +16,7 @@ import ( // swagger:operation GET /api/v1/users/{user} users GetUser // -// Retrieve a user for the configured backend +// Get a user // // --- // produces: @@ -34,13 +34,16 @@ import ( // description: Successfully retrieved the user // schema: // "$ref": "#/definitions/User" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve the user +// description: Not found // schema: // "$ref": "#/definitions/Error" -// GetUser represents the API handler to capture a -// user from the configured backend. +// GetUser represents the API handler to get a user. func GetUser(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/user/get_current.go b/api/user/get_current.go index 455a4e8e7..1cd21526d 100644 --- a/api/user/get_current.go +++ b/api/user/get_current.go @@ -13,7 +13,7 @@ import ( // swagger:operation GET /api/v1/user users GetCurrentUser // -// Retrieve the current authenticated user from the configured backend +// Get the current authenticated user // // --- // produces: @@ -25,9 +25,13 @@ import ( // description: Successfully retrieved the current user // schema: // "$ref": "#/definitions/User" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // GetCurrentUser represents the API handler to capture the -// currently authenticated user from the configured backend. +// currently authenticated user. func GetCurrentUser(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/user/get_source.go b/api/user/get_source.go index d0b666090..b74639f96 100644 --- a/api/user/get_source.go +++ b/api/user/get_source.go @@ -18,7 +18,7 @@ import ( // swagger:operation GET /api/v1/user/source/repos users GetSourceRepos // -// Retrieve a list of repos for the current authenticated user +// Get all repos for the current authenticated user // // --- // produces: @@ -30,13 +30,16 @@ import ( // description: Successfully retrieved a list of repos for the current user // schema: // "$ref": "#/definitions/Repo" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve a list of repos for the current user +// description: Not found // schema: // "$ref": "#/definitions/Error" -// GetSourceRepos represents the API handler to capture -// the list of repos for a user from the configured backend. +// GetSourceRepos represents the API handler to get a list of repos for a user. func GetSourceRepos(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/user/list.go b/api/user/list.go index 55f67f64e..d4f5ad0ff 100644 --- a/api/user/list.go +++ b/api/user/list.go @@ -18,7 +18,7 @@ import ( // swagger:operation GET /api/v1/users users ListUsers // -// Retrieve a list of users for the configured backend +// Get all users // // --- // produces: @@ -49,19 +49,22 @@ import ( // description: Total number of results // type: integer // Link: -// description: see https://tools.ietf.org/html/rfc5988 +// description: See https://tools.ietf.org/html/rfc5988 // type: string // '400': -// description: Unable to retrieve the list of users +// description: Invalid request payload +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the list of users +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListUsers represents the API handler to capture a list -// of users from the configured backend. +// ListUsers represents the API handler to get a list of users. func ListUsers(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/user/update.go b/api/user/update.go index 3983abd0f..9ebd37c36 100644 --- a/api/user/update.go +++ b/api/user/update.go @@ -17,7 +17,7 @@ import ( // swagger:operation PUT /api/v1/users/{user} users UpdateUser // -// Update a user for the configured backend +// Update a user // // --- // produces: @@ -30,7 +30,7 @@ import ( // type: string // - in: body // name: body -// description: Payload containing the user to update +// description: The user object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/User" @@ -42,20 +42,23 @@ import ( // schema: // "$ref": "#/definitions/User" // '400': -// description: Unable to update the user +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to update the user +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the user +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// UpdateUser represents the API handler to update -// a user in the configured backend. +// UpdateUser represents the API handler to update a user. func UpdateUser(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/user/update_current.go b/api/user/update_current.go index dec97ba71..3853611ec 100644 --- a/api/user/update_current.go +++ b/api/user/update_current.go @@ -17,7 +17,7 @@ import ( // swagger:operation PUT /api/v1/user users UpdateCurrentUser // -// Update the current authenticated user in the configured backend +// Update the current authenticated user // // --- // produces: @@ -25,7 +25,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing the user to update +// description: The user object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/User" @@ -37,20 +37,20 @@ import ( // schema: // "$ref": "#/definitions/User" // '400': -// description: Unable to update the current user +// description: Invalid request payload // schema: // "$ref": "#/definitions/Error" -// '404': -// description: Unable to update the current user +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the current user +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // UpdateCurrentUser represents the API handler to capture and -// update the currently authenticated user from the configured backend. +// update the currently authenticated user. func UpdateCurrentUser(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/version.go b/api/version.go index 349fd5ea4..726e7cc3f 100644 --- a/api/version.go +++ b/api/version.go @@ -12,7 +12,7 @@ import ( // swagger:operation GET /version base Version // -// Get the version of the Vela API +// Get the Vela API version // // --- // produces: diff --git a/api/webhook/post.go b/api/webhook/post.go index 50d69d315..ddc0a047e 100644 --- a/api/webhook/post.go +++ b/api/webhook/post.go @@ -33,7 +33,7 @@ var baseErr = "unable to process webhook" // swagger:operation POST /webhook base PostWebhook // -// Deliver a webhook to the vela api +// Deliver a webhook to the Vela API // // --- // produces: @@ -56,15 +56,15 @@ var baseErr = "unable to process webhook" // schema: // "$ref": "#/definitions/Build" // '400': -// description: Malformed webhook payload or improper pipeline configuration +// description: Invalid request payload // schema: // "$ref": "#/definitions/Error" // '401': -// description: Repository owner does not have proper access +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to receive the webhook +// description: Not found // schema: // "$ref": "#/definitions/Error" // '429': @@ -72,7 +72,7 @@ var baseErr = "unable to process webhook" // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to receive the webhook or internal error while processing +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/worker/create.go b/api/worker/create.go index 557cb1858..c8af50b5e 100644 --- a/api/worker/create.go +++ b/api/worker/create.go @@ -23,7 +23,7 @@ import ( // swagger:operation POST /api/v1/workers workers CreateWorker // -// Create a worker for the configured backend +// Create a worker // // --- // produces: @@ -31,7 +31,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing the worker to create +// description: Worker object to create // required: true // schema: // "$ref": "#/definitions/Worker" @@ -43,16 +43,20 @@ import ( // schema: // "$ref": "#/definitions/Token" // '400': -// description: Unable to create the worker +// description: Invalid request payload +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to create the worker +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // CreateWorker represents the API handler to -// create a worker in the configured backend. +// create a worker. func CreateWorker(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/worker/delete.go b/api/worker/delete.go index ebb718aeb..84f1442c0 100644 --- a/api/worker/delete.go +++ b/api/worker/delete.go @@ -17,7 +17,7 @@ import ( // swagger:operation DELETE /api/v1/workers/{worker} workers DeleteWorker // -// Delete a worker for the configured backend +// Delete a worker // // --- // produces: @@ -32,16 +32,27 @@ import ( // - ApiKeyAuth: [] // responses: // '200': -// description: Successfully deleted of worker +// description: Successfully deleted worker // schema: // type: string +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" +// '404': +// description: Not found +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to delete worker +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// DeleteWorker represents the API handler to remove -// a worker from the configured backend. +// DeleteWorker represents the API handler to remove a worker. func DeleteWorker(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/worker/get.go b/api/worker/get.go index 64ce34173..c7d3f5227 100644 --- a/api/worker/get.go +++ b/api/worker/get.go @@ -18,7 +18,7 @@ import ( // swagger:operation GET /api/v1/workers/{worker} workers GetWorker // -// Retrieve a worker for the configured backend +// Get a worker // // --- // produces: @@ -36,13 +36,24 @@ import ( // description: Successfully retrieved the worker // schema: // "$ref": "#/definitions/Worker" +// '400': +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '404': -// description: Unable to retrieve the worker +// description: Not found +// schema: +// "$ref": "#/definitions/Error" +// '500': +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// GetWorker represents the API handler to capture a -// worker from the configured backend. +// GetWorker represents the API handler to get a worker. func GetWorker(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/worker/list.go b/api/worker/list.go index 5141335ba..eb20d58f8 100644 --- a/api/worker/list.go +++ b/api/worker/list.go @@ -19,7 +19,7 @@ import ( // swagger:operation GET /api/v1/workers workers ListWorkers // -// Retrieve a list of workers for the configured backend +// Get all workers // // --- // produces: @@ -31,11 +31,11 @@ import ( // type: boolean // - in: query // name: checked_in_before -// description: filter workers that have checked in before a certain time +// description: Filter workers that have checked in before a certain time // type: integer // - in: query // name: checked_in_after -// description: filter workers that have checked in after a certain time +// description: Filter workers that have checked in after a certain time // type: integer // default: 0 // security: @@ -47,13 +47,20 @@ import ( // type: array // items: // "$ref": "#/definitions/Worker" +// '400': +// description: Invalid request payload +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized +// schema: +// "$ref": "#/definitions/Error" // '500': -// description: Unable to retrieve the list of workers +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" -// ListWorkers represents the API handler to capture a -// list of workers from the configured backend. +// ListWorkers represents the API handler to get a list of workers. func ListWorkers(c *gin.Context) { // capture middleware values u := user.Retrieve(c) diff --git a/api/worker/refresh.go b/api/worker/refresh.go index 4aff87a17..5fca4b884 100644 --- a/api/worker/refresh.go +++ b/api/worker/refresh.go @@ -22,7 +22,7 @@ import ( // swagger:operation POST /api/v1/workers/{worker}/refresh workers RefreshWorkerAuth // -// Refresh authorization token for worker +// Refresh authorization token for a worker // // --- // produces: @@ -41,15 +41,19 @@ import ( // schema: // "$ref": "#/definitions/Token" // '400': -// description: Unable to refresh worker auth +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to refresh worker auth +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to refresh worker auth +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" diff --git a/api/worker/update.go b/api/worker/update.go index db187b7c0..b717f9838 100644 --- a/api/worker/update.go +++ b/api/worker/update.go @@ -18,7 +18,7 @@ import ( // swagger:operation PUT /api/v1/workers/{worker} workers UpdateWorker // -// Update a worker for the configured backend +// Update a worker // // --- // produces: @@ -26,7 +26,7 @@ import ( // parameters: // - in: body // name: body -// description: Payload containing the worker to update +// description: The worker object with the fields to be updated // required: true // schema: // "$ref": "#/definitions/Worker" @@ -43,20 +43,24 @@ import ( // schema: // "$ref": "#/definitions/Worker" // '400': -// description: Unable to update the worker +// description: Invalid request payload or path +// schema: +// "$ref": "#/definitions/Error" +// '401': +// description: Unauthorized // schema: // "$ref": "#/definitions/Error" // '404': -// description: Unable to update the worker +// description: Not found // schema: // "$ref": "#/definitions/Error" // '500': -// description: Unable to update the worker +// description: Unexpected server error // schema: // "$ref": "#/definitions/Error" // UpdateWorker represents the API handler to -// update a worker in the configured backend. +// update a worker. func UpdateWorker(c *gin.Context) { // capture middleware values u := user.Retrieve(c)