fix(swagger): various fixes and improved consistency

well, well.. started with fixing some errors i noticed in the swagger
annotations and quickly turned into a rabbit hole of fixing and trying
to improve various things.

however, here are some highlights:
- correct flat out errors in swagger annotations
- ensure all response codes are covered
- simplify language (also meant removing some unnecessary language)
- improve consistency in language

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,36 +73,35 @@ func AllBuildsQueue(c *gin.Context) {
 
 // swagger:operation PUT /api/v1/admin/build admin AdminUpdateBuild
 //
-// Update a build in the database
+// Update a build
 //
 // ---
 // produces:
 // - application/json
 // 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"
 // security:
 //   - 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
 	}

api/admin/clean.go

@@ -20,15 +20,15 @@ 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:
 // - application/json
 // 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)

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.")
 }

api/admin/hook.go

@@ -17,36 +17,39 @@ import (
 
 // swagger:operation PUT /api/v1/admin/hook admin AdminUpdateHook
 //
-// Update a hook in the database
+// Update a hook
 //
 // ---
 // produces:
 // - application/json
 // 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"
 // security:
 //   - 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
 	}

api/admin/repo.go

@@ -17,36 +17,39 @@ import (
 
 // swagger:operation PUT /api/v1/admin/repo admin AdminUpdateRepo
 //
-// Update a repo in the database
+// Update a repository
 //
 // ---
 // produces:
 // - application/json
 // 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"
 // security:
 //   - 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
 	}

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")
 

api/admin/secret.go

@@ -17,36 +17,39 @@ import (
 
 // swagger:operation PUT /api/v1/admin/secret admin AdminUpdateSecret
 //
-// Update a secret in the database
+// Update a secret
 //
 // ---
 // produces:
 // - application/json
 // 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"
 // security:
 //   - 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
 	}