From befeacdf7dd930d98a032291fca964254fa55297 Mon Sep 17 00:00:00 2001 From: Mitrahsoft Date: Fri, 14 Aug 2026 08:25:44 +0530 Subject: [PATCH] docs(api): document 401/403 responses for user key endpoints (#38711) --- routers/api/v1/user/gpg_key.go | 22 +++++++ routers/api/v1/user/key.go | 14 ++++ services/context/api.go | 6 ++ templates/swagger/v1-openapi3.generated.json | 69 ++++++++++++++++++++ templates/swagger/v1-swagger.generated.json | 65 ++++++++++++++++++ 5 files changed, 176 insertions(+) diff --git a/routers/api/v1/user/gpg_key.go b/routers/api/v1/user/gpg_key.go index bb6f840ec1c..58637775a36 100644 --- a/routers/api/v1/user/gpg_key.go +++ b/routers/api/v1/user/gpg_key.go @@ -91,6 +91,10 @@ func ListMyGPGKeys(ctx *context.APIContext) { // responses: // "200": // "$ref": "#/responses/GPGKeyList" + // "401": + // "$ref": "#/responses/unauthorized" + // "403": + // "$ref": "#/responses/forbidden" listGPGKeys(ctx, ctx.Doer.ID, utils.GetListOptions(ctx)) } @@ -112,6 +116,10 @@ func GetGPGKey(ctx *context.APIContext) { // responses: // "200": // "$ref": "#/responses/GPGKey" + // "401": + // "$ref": "#/responses/unauthorized" + // "403": + // "$ref": "#/responses/forbidden" // "404": // "$ref": "#/responses/notFound" @@ -163,6 +171,10 @@ func GetVerificationToken(ctx *context.APIContext) { // responses: // "200": // "$ref": "#/responses/string" + // "401": + // "$ref": "#/responses/unauthorized" + // "403": + // "$ref": "#/responses/forbidden" // "404": // "$ref": "#/responses/notFound" @@ -182,6 +194,10 @@ func VerifyUserGPGKey(ctx *context.APIContext) { // responses: // "201": // "$ref": "#/responses/GPGKey" + // "401": + // "$ref": "#/responses/unauthorized" + // "403": + // "$ref": "#/responses/forbidden" // "404": // "$ref": "#/responses/notFound" // "422": @@ -243,6 +259,10 @@ func CreateGPGKey(ctx *context.APIContext) { // responses: // "201": // "$ref": "#/responses/GPGKey" + // "401": + // "$ref": "#/responses/unauthorized" + // "403": + // "$ref": "#/responses/forbidden" // "404": // "$ref": "#/responses/notFound" // "422": @@ -269,6 +289,8 @@ func DeleteGPGKey(ctx *context.APIContext) { // responses: // "204": // "$ref": "#/responses/empty" + // "401": + // "$ref": "#/responses/unauthorized" // "403": // "$ref": "#/responses/forbidden" // "404": diff --git a/routers/api/v1/user/key.go b/routers/api/v1/user/key.go index 4572e9ce8b4..76e8fb9d642 100644 --- a/routers/api/v1/user/key.go +++ b/routers/api/v1/user/key.go @@ -121,6 +121,10 @@ func ListMyPublicKeys(ctx *context.APIContext) { // responses: // "200": // "$ref": "#/responses/PublicKeyList" + // "401": + // "$ref": "#/responses/unauthorized" + // "403": + // "$ref": "#/responses/forbidden" listPublicKeys(ctx, ctx.Doer) } @@ -176,6 +180,10 @@ func GetPublicKey(ctx *context.APIContext) { // responses: // "200": // "$ref": "#/responses/PublicKey" + // "401": + // "$ref": "#/responses/unauthorized" + // "403": + // "$ref": "#/responses/forbidden" // "404": // "$ref": "#/responses/notFound" @@ -240,6 +248,10 @@ func CreatePublicKey(ctx *context.APIContext) { // responses: // "201": // "$ref": "#/responses/PublicKey" + // "401": + // "$ref": "#/responses/unauthorized" + // "403": + // "$ref": "#/responses/forbidden" // "422": // "$ref": "#/responses/validationError" @@ -264,6 +276,8 @@ func DeletePublicKey(ctx *context.APIContext) { // responses: // "204": // "$ref": "#/responses/empty" + // "401": + // "$ref": "#/responses/unauthorized" // "403": // "$ref": "#/responses/forbidden" // "404": diff --git a/services/context/api.go b/services/context/api.go index 9b6cc33c7eb..9a5e7fec3a8 100644 --- a/services/context/api.go +++ b/services/context/api.go @@ -97,6 +97,12 @@ type APIForbiddenError struct { APIError } +// APIUnauthorizedError is an unauthorized error response +// swagger:response unauthorized +type APIUnauthorizedError struct { + APIError +} + // APINotFound is a not found empty response // swagger:response notFound type APINotFound struct{} diff --git a/templates/swagger/v1-openapi3.generated.json b/templates/swagger/v1-openapi3.generated.json index 824949a5dca..cb2423be78e 100644 --- a/templates/swagger/v1-openapi3.generated.json +++ b/templates/swagger/v1-openapi3.generated.json @@ -1711,6 +1711,21 @@ }, "description": "APIString is a string response" }, + "unauthorized": { + "description": "APIUnauthorizedError is an unauthorized error response", + "headers": { + "message": { + "schema": { + "type": "string" + } + }, + "url": { + "schema": { + "type": "string" + } + } + } + }, "validationError": { "description": "APIValidationError is error format response related to input validation", "headers": { @@ -34970,6 +34985,12 @@ "200": { "$ref": "#/components/responses/string" }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, "404": { "$ref": "#/components/responses/notFound" } @@ -34987,6 +35008,12 @@ "201": { "$ref": "#/components/responses/GPGKey" }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, "404": { "$ref": "#/components/responses/notFound" }, @@ -35024,6 +35051,12 @@ "responses": { "200": { "$ref": "#/components/responses/GPGKeyList" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" } }, "summary": "List the authenticated user's GPG keys", @@ -35047,6 +35080,12 @@ "201": { "$ref": "#/components/responses/GPGKey" }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, "404": { "$ref": "#/components/responses/notFound" }, @@ -35079,6 +35118,9 @@ "204": { "$ref": "#/components/responses/empty" }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, "403": { "$ref": "#/components/responses/forbidden" }, @@ -35109,6 +35151,12 @@ "200": { "$ref": "#/components/responses/GPGKey" }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, "404": { "$ref": "#/components/responses/notFound" } @@ -35290,6 +35338,12 @@ "responses": { "200": { "$ref": "#/components/responses/PublicKeyList" + }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" } }, "summary": "List the authenticated user's public keys", @@ -35313,6 +35367,12 @@ "201": { "$ref": "#/components/responses/PublicKey" }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, "422": { "$ref": "#/components/responses/validationError" } @@ -35342,6 +35402,9 @@ "204": { "$ref": "#/components/responses/empty" }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, "403": { "$ref": "#/components/responses/forbidden" }, @@ -35372,6 +35435,12 @@ "200": { "$ref": "#/components/responses/PublicKey" }, + "401": { + "$ref": "#/components/responses/unauthorized" + }, + "403": { + "$ref": "#/components/responses/forbidden" + }, "404": { "$ref": "#/components/responses/notFound" } diff --git a/templates/swagger/v1-swagger.generated.json b/templates/swagger/v1-swagger.generated.json index bc4a38f21e6..500e6b06f89 100644 --- a/templates/swagger/v1-swagger.generated.json +++ b/templates/swagger/v1-swagger.generated.json @@ -22325,6 +22325,12 @@ "200": { "$ref": "#/responses/string" }, + "401": { + "$ref": "#/responses/unauthorized" + }, + "403": { + "$ref": "#/responses/forbidden" + }, "404": { "$ref": "#/responses/notFound" } @@ -22348,6 +22354,12 @@ "201": { "$ref": "#/responses/GPGKey" }, + "401": { + "$ref": "#/responses/unauthorized" + }, + "403": { + "$ref": "#/responses/forbidden" + }, "404": { "$ref": "#/responses/notFound" }, @@ -22384,6 +22396,12 @@ "responses": { "200": { "$ref": "#/responses/GPGKeyList" + }, + "401": { + "$ref": "#/responses/unauthorized" + }, + "403": { + "$ref": "#/responses/forbidden" } } }, @@ -22412,6 +22430,12 @@ "201": { "$ref": "#/responses/GPGKey" }, + "401": { + "$ref": "#/responses/unauthorized" + }, + "403": { + "$ref": "#/responses/forbidden" + }, "404": { "$ref": "#/responses/notFound" }, @@ -22445,6 +22469,12 @@ "200": { "$ref": "#/responses/GPGKey" }, + "401": { + "$ref": "#/responses/unauthorized" + }, + "403": { + "$ref": "#/responses/forbidden" + }, "404": { "$ref": "#/responses/notFound" } @@ -22473,6 +22503,9 @@ "204": { "$ref": "#/responses/empty" }, + "401": { + "$ref": "#/responses/unauthorized" + }, "403": { "$ref": "#/responses/forbidden" }, @@ -22661,6 +22694,12 @@ "responses": { "200": { "$ref": "#/responses/PublicKeyList" + }, + "401": { + "$ref": "#/responses/unauthorized" + }, + "403": { + "$ref": "#/responses/forbidden" } } }, @@ -22689,6 +22728,12 @@ "201": { "$ref": "#/responses/PublicKey" }, + "401": { + "$ref": "#/responses/unauthorized" + }, + "403": { + "$ref": "#/responses/forbidden" + }, "422": { "$ref": "#/responses/validationError" } @@ -22719,6 +22764,12 @@ "200": { "$ref": "#/responses/PublicKey" }, + "401": { + "$ref": "#/responses/unauthorized" + }, + "403": { + "$ref": "#/responses/forbidden" + }, "404": { "$ref": "#/responses/notFound" } @@ -22747,6 +22798,9 @@ "204": { "$ref": "#/responses/empty" }, + "401": { + "$ref": "#/responses/unauthorized" + }, "403": { "$ref": "#/responses/forbidden" }, @@ -34949,6 +35003,17 @@ "type": "string" } }, + "unauthorized": { + "description": "APIUnauthorizedError is an unauthorized error response", + "headers": { + "message": { + "type": "string" + }, + "url": { + "type": "string" + } + } + }, "validationError": { "description": "APIValidationError is error format response related to input validation", "headers": {