oss/forgejo
oss/forgejo
1
0
Fork 0
mirror of https://codeberg.org/forgejo/forgejo.git synced 2025-09-30 19:22:08 +00:00
Code Wiki Activity

Update Swagger annotations to reflect actual behavior (#9138)

Browse source 
## Checklist

The [contributor guide](https://forgejo.org/docs/next/contributor/) contains information that will be helpful to first time contributors. There also are a few [conditions for merging Pull Requests in Forgejo repositories](https://codeberg.org/forgejo/governance/src/branch/main/PullRequestsAgreement.md). You are also welcome to join the [Forgejo development chatroom](https://matrix.to/#/#forgejo-development:matrix.org).

### Tests

- I added test coverage for Go changes...
  - [ ] in their respective `*_test.go` for unit tests.
  - [ ] in the `tests/integration` directory if it involves interactions with a live Forgejo server.
- I added test coverage for JavaScript changes...
  - [ ] in `web_src/js/*.test.js` if it can be unit tested.
  - [ ] in `tests/e2e/*.test.e2e.js` if it requires interactions with a live Forgejo server (see also the [developer guide for JavaScript testing](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/tests/e2e/README.md#end-to-end-tests)).

### Documentation

- [ ] I created a pull request [to the documentation](https://codeberg.org/forgejo/docs) to explain to Forgejo users how to use this change.
- [x] I did not document these changes and I do not expect someone else to do it.

### Release notes

- [ ] I do not want this change to show in the release notes.
- [x] I want the title to show in the release notes with a link to this pull request.
- [ ] I want the content of the `release-notes/<pull request number>.md` to be be used for the release notes instead of the title.

----

This is a fix for the Swagger annotations reported in #8918.
Most of the changes are corrections to annotation comments, with some additions of wrapper struct definitions for Swagger auto‑generation.

Co-authored-by: toras9000 <toras9000@example.com>
Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/9138
Reviewed-by: Lucas <sclu1034@noreply.codeberg.org>
Co-authored-by: toras9000 <toras9000@noreply.codeberg.org>
Co-committed-by: toras9000 <toras9000@noreply.codeberg.org>
This commit is contained in:
toras9000 2025-09-15 11:55:49 +02:00 • committed by Earl Warren
parent b755f09e95
commit 5c6645a8af
24 changed files with 257 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

2
routers/api/v1/activitypub/person.go
View file

@ -32,6 +32,7 @@ func Person(ctx *context.APIContext) {
// in: path
// description: user ID of the user
// type: integer
// format: int64
// required: true
// responses:
// "200":
@ -67,6 +68,7 @@ func PersonInbox(ctx *context.APIContext) {
// in: path
// description: user ID of the user
// type: integer
// format: int64
// required: true
// responses:
// "202":

2
routers/api/v1/activitypub/repository.go
View file

@ -30,6 +30,7 @@ func Repository(ctx *context.APIContext) {
// in: path
// description: repository ID of the repo
// type: integer
// format: int64
// required: true
// responses:
// "200":
@ -59,6 +60,7 @@ func RepositoryInbox(ctx *context.APIContext) {
// in: path
// description: repository ID of the repo
// type: integer
// format: int64
// required: true
// - name: body
// in: body

2
routers/api/v1/notify/repo.go
View file

@ -153,7 +153,7 @@ func ReadRepoNotifications(ctx *context.APIContext) {
// - name: all
// in: query
// description: If true, mark all notifications on this repo. Default value is false
// type: string
// type: boolean
// required: false
// - name: status-types
// in: query

6
routers/api/v1/notify/threads.go
View file

@ -27,7 +27,8 @@ func GetThread(ctx *context.APIContext) {
// - name: id
// in: path
// description: id of notification thread
// type: string
// type: integer
// format: int64
// required: true
// responses:
// "200":
@ -62,7 +63,8 @@ func ReadThread(ctx *context.APIContext) {
// - name: id
// in: path
// description: id of notification thread
// type: string
// type: integer
// format: int64
// required: true
// - name: to-status
// in: query

2
routers/api/v1/notify/user.go
View file

@ -109,7 +109,7 @@ func ReadNotifications(ctx *context.APIContext) {
// - name: all
// in: query
// description: If true, mark all notifications on this repo. Default value is false
// type: string
// type: boolean
// required: false
// - name: status-types
// in: query

4
routers/api/v1/org/action.go
View file

@ -334,10 +334,6 @@ func (Action) DeleteVariable(ctx *context.APIContext) {
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/ActionVariable"
// "201":
// description: response when deleting a variable
// "204":
// description: response when deleting a variable
// "400":

5
routers/api/v1/org/label.go
View file

@ -30,6 +30,11 @@ func ListLabels(ctx *context.APIContext) {
// description: name of the organization
// type: string
// required: true
// - name: sort
// in: query
// description: "Specifies the sorting method: mostissues, leastissues, or reversealphabetically."
// type: string
// enum: [mostissues, leastissues, reversealphabetically]
// - name: page
// in: query
// description: page number of results to return (1-based)

9
routers/api/v1/org/quota.go
View file

@ -45,9 +45,16 @@ func CheckQuota(ctx *context.APIContext) {
// description: name of the organization
// type: string
// required: true
// - name: subject
// in: query
// description: subject of the quota
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/boolean"
// description: Returns true if the action is accepted.
// schema:
// type: boolean
// "403":
// "$ref": "#/responses/forbidden"
// "404":

2
routers/api/v1/org/team.go
View file

@ -274,6 +274,7 @@ func EditTeam(ctx *context.APIContext) {
// in: path
// description: id of the team to edit
// type: integer
// format: int64
// required: true
// - name: body
// in: body
@ -790,6 +791,7 @@ func SearchTeam(ctx *context.APIContext) {
// description: "SearchResults of a successful search"
// schema:
// type: object
// title: "TeamSearchResults"
// properties:
// ok:
// type: boolean

4
routers/api/v1/repo/action.go
View file

@ -268,10 +268,6 @@ func (Action) DeleteVariable(ctx *context.APIContext) {
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/ActionVariable"
// "201":
// description: response when deleting a variable
// "204":
// description: response when deleting a variable
// "400":

6
routers/api/v1/repo/file.go
View file

@ -405,7 +405,11 @@ func GetEditorconfig(ctx *context.APIContext) {
// required: false
// responses:
// 200:
// description: success
// description: definitions
// schema:
// type: object
// additionalProperties:
// type: string
// "404":
// "$ref": "#/responses/notFound"

18
routers/api/v1/repo/issue_dependency.go
View file

@ -39,7 +39,8 @@ func GetIssueDependencies(ctx *context.APIContext) {
// - name: index
// in: path
// description: index of the issue
// type: string
// type: integer
// format: int64
// required: true
// - name: page
// in: query
@ -177,7 +178,8 @@ func CreateIssueDependency(ctx *context.APIContext) {
// - name: index
// in: path
// description: index of the issue
// type: string
// type: integer
// format: int64
// required: true
// - name: body
// in: body
@ -238,7 +240,8 @@ func RemoveIssueDependency(ctx *context.APIContext) {
// - name: index
// in: path
// description: index of the issue
// type: string
// type: integer
// format: int64
// required: true
// - name: body
// in: body
@ -299,7 +302,8 @@ func GetIssueBlocks(ctx *context.APIContext) {
// - name: index
// in: path
// description: index of the issue
// type: string
// type: integer
// format: int64
// required: true
// - name: page
// in: query
@ -405,7 +409,8 @@ func CreateIssueBlocking(ctx *context.APIContext) {
// - name: index
// in: path
// description: index of the issue
// type: string
// type: integer
// format: int64
// required: true
// - name: body
// in: body
@ -462,7 +467,8 @@ func RemoveIssueBlocking(ctx *context.APIContext) {
// - name: index
// in: path
// description: index of the issue
// type: string
// type: integer
// format: int64
// required: true
// - name: body
// in: body

5
routers/api/v1/repo/label.go
View file

@ -35,6 +35,11 @@ func ListLabels(ctx *context.APIContext) {
// description: name of the repo
// type: string
// required: true
// - name: sort
// in: query
// description: "Specifies the sorting method: mostissues, leastissues, or reversealphabetically."
// type: string
// enum: [mostissues, leastissues, reversealphabetically]
// - name: page
// in: query
// description: page number of results to return (1-based)

9
routers/api/v1/repo/milestone.go
View file

@ -108,7 +108,8 @@ func GetMilestone(ctx *context.APIContext) {
// - name: id
// in: path
// description: the milestone to get, identified by ID and if not available by name
// type: string
// type: integer
// format: int64
// required: true
// responses:
// "200":
@ -202,7 +203,8 @@ func EditMilestone(ctx *context.APIContext) {
// - name: id
// in: path
// description: the milestone to edit, identified by ID and if not available by name
// type: string
// type: integer
// format: int64
// required: true
// - name: body
// in: body
@ -260,7 +262,8 @@ func DeleteMilestone(ctx *context.APIContext) {
// - name: id
// in: path
// description: the milestone to delete, identified by ID and if not available by name
// type: string
// type: integer
// format: int64
// required: true
// responses:
// "204":

2
routers/api/v1/repo/repo.go
View file

@ -110,11 +110,13 @@ func Search(ctx *context.APIContext) {
// "alpha", "created", "updated", "size", "git_size", "lfs_size", "stars", "forks" and "id".
// Default is "alpha"
// type: string
// enum: [alpha, created, updated, size, git_size, lfs_size, id, stars, forks]
// - name: order
// in: query
// description: sort order, either "asc" (ascending) or "desc" (descending).
// Default is "asc", ignored if "sort" is not specified.
// type: string
// enum: [asc, desc]
// - name: page
// in: query
// description: page number of results to return (1-based)

3
routers/api/v1/repo/tag.go
View file

@ -380,6 +380,7 @@ func GetTagProtection(ctx *context.APIContext) {
// in: path
// description: id of the tag protect to get
// type: integer
// format: int64
// required: true
// responses:
// "200":
@ -534,6 +535,7 @@ func EditTagProtection(ctx *context.APIContext) {
// in: path
// description: id of protected tag
// type: integer
// format: int64
// required: true
// - name: body
// in: body
@ -639,6 +641,7 @@ func DeleteTagProtection(ctx *context.APIContext) {
// in: path
// description: id of protected tag
// type: integer
// format: int64
// required: true
// responses:
// "204":

10
routers/api/v1/repo/topic.go
View file

@ -276,7 +276,15 @@ func TopicSearch(ctx *context.APIContext) {
// type: integer
// responses:
// "200":
// "$ref": "#/responses/TopicListResponse"
// description: "SearchResults of a successful search"
// schema:
// type: object
// title: "TopicSearchResults"
// properties:
// topics:
// type: array
// items:
// "$ref": "#/definitions/TopicResponse"
// "403":
// "$ref": "#/responses/forbidden"
// "404":

1
routers/api/v1/shared/runners.go
View file

@ -16,7 +16,6 @@ import (
)
// RegistrationToken is a string used to register a runner with a server
// swagger:response RegistrationToken
type RegistrationToken struct {
Token string `json:"token"`
}

12
routers/api/v1/swagger/action.go
View file

@ -3,7 +3,10 @@
package swagger
import api "forgejo.org/modules/structs"
import (
api "forgejo.org/modules/structs"
shared "forgejo.org/routers/api/v1/shared"
)
// SecretList
// swagger:response SecretList
@ -46,3 +49,10 @@ type swaggerDispatchWorkflowRun struct {
// in:body
Body *api.DispatchWorkflowRun `json:"body"`
}
// RegistrationToken is a string used to register a runner with a server
// swagger:response RegistrationToken
type swaggerRegistrationToken struct {
// in: body
Body shared.RegistrationToken `json:"body"`
}

2
routers/api/v1/swagger/repo.go
View file

@ -460,7 +460,7 @@ type swaggerCompare struct {
// swagger:response SyncForkInfo
type swaggerSyncForkInfo struct {
// in:body
Body []api.SyncForkInfo `json:"body"`
Body api.SyncForkInfo `json:"body"`
}
// ActionRunList

11
routers/api/v1/user/gpg_key.go
View file

@ -184,6 +184,12 @@ func GetVerificationToken(ctx *context.APIContext) {
ctx.PlainText(http.StatusOK, token)
}
// swagger:parameters userVerifyGPGKey
type swaggerUserVerifyGPGKey struct {
// in:body
Form api.VerifyGPGKeyOption
}
// VerifyUserGPGKey creates new GPG key to given user by ID.
func VerifyUserGPGKey(ctx *context.APIContext) {
// swagger:operation POST /user/gpg_key_verify user userVerifyGPGKey
@ -193,6 +199,11 @@ func VerifyUserGPGKey(ctx *context.APIContext) {
// - application/json
// produces:
// - application/json
// parameters:
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/VerifyGPGKeyOption"
// responses:
// "201":
// "$ref": "#/responses/GPGKey"

10
routers/api/v1/user/quota.go
View file

@ -33,9 +33,17 @@ func CheckQuota(ctx *context.APIContext) {
// summary: Check if the authenticated user is over quota for a given subject
// produces:
// - application/json
// parameters:
// - name: subject
// in: query
// description: subject of the quota
// type: string
// required: true
// responses:
// "200":
// "$ref": "#/responses/boolean"
// description: Returns true if the action is accepted.
// schema:
// type: boolean
// "401":
// "$ref": "#/responses/unauthorized"
// "403":

1
routers/api/v1/user/user.go
View file

@ -51,6 +51,7 @@ func Search(ctx *context.APIContext) {
// description: "SearchResults of a successful search"
// schema:
// type: object
// title: "UserSearchResults"
// properties:
// ok:
// type: boolean

194
templates/swagger/v1_json.tmpl generated
View file

@ -70,6 +70,7 @@
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "repository ID of the repo",
"name": "repository-id",
"in": "path",
@ -96,6 +97,7 @@
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "repository ID of the repo",
"name": "repository-id",
"in": "path",
@ -129,6 +131,7 @@
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "user ID of the user",
"name": "user-id",
"in": "path",
@ -221,6 +224,7 @@
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "user ID of the user",
"name": "user-id",
"in": "path",
@ -2081,7 +2085,7 @@
"in": "query"
},
{
"type": "string",
"type": "boolean",
"description": "If true, mark all notifications on this repo. Default value is false",
"name": "all",
"in": "query"
@ -2139,7 +2143,8 @@
"operationId": "notifyGetThread",
"parameters": [
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "id of notification thread",
"name": "id",
"in": "path",
@ -2172,7 +2177,8 @@
"operationId": "notifyReadThread",
"parameters": [
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "id of notification thread",
"name": "id",
"in": "path",
@ -2809,12 +2815,6 @@
}
],
"responses": {
"200": {
"$ref": "#/responses/ActionVariable"
},
"201": {
"description": "response when deleting a variable"
},
"204": {
"description": "response when deleting a variable"
},
@ -3191,6 +3191,17 @@
"in": "path",
"required": true
},
{
"enum": [
"mostissues",
"leastissues",
"reversealphabetically"
],
"type": "string",
"description": "Specifies the sorting method: mostissues, leastissues, or reversealphabetically.",
"name": "sort",
"in": "query"
},
{
"type": "integer",
"description": "page number of results to return (1-based)",
@ -3805,11 +3816,21 @@
"name": "org",
"in": "path",
"required": true
},
{
"type": "string",
"description": "subject of the quota",
"name": "subject",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"$ref": "#/responses/boolean"
"description": "Returns true if the action is accepted.",
"schema": {
"type": "boolean"
}
},
"403": {
"$ref": "#/responses/forbidden"
@ -4120,6 +4141,7 @@
"description": "SearchResults of a successful search",
"schema": {
"type": "object",
"title": "TeamSearchResults",
"properties": {
"data": {
"type": "array",
@ -4787,12 +4809,27 @@
"in": "query"
},
{
"enum": [
"alpha",
"created",
"updated",
"size",
"git_size",
"lfs_size",
"id",
"stars",
"forks"
],
"type": "string",
"description": "sort repos by attribute. Supported values are \"alpha\", \"created\", \"updated\", \"size\", \"git_size\", \"lfs_size\", \"stars\", \"forks\" and \"id\". Default is \"alpha\"",
"name": "sort",
"in": "query"
},
{
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "sort order, either \"asc\" (ascending) or \"desc\" (descending). Default is \"asc\", ignored if \"sort\" is not specified.",
"name": "order",
@ -5610,12 +5647,6 @@
}
],
"responses": {
"200": {
"$ref": "#/responses/ActionVariable"
},
"201": {
"description": "response when deleting a variable"
},
"204": {
"description": "response when deleting a variable"
},
@ -7408,7 +7439,13 @@
],
"responses": {
"200": {
"description": "success"
"description": "definitions",
"schema": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"404": {
"$ref": "#/responses/notFound"
@ -10249,7 +10286,8 @@
"required": true
},
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "index of the issue",
"name": "index",
"in": "path",
@ -10302,7 +10340,8 @@
"required": true
},
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "index of the issue",
"name": "index",
"in": "path",
@ -10350,7 +10389,8 @@
"required": true
},
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "index of the issue",
"name": "index",
"in": "path",
@ -10703,7 +10743,8 @@
"required": true
},
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "index of the issue",
"name": "index",
"in": "path",
@ -10756,7 +10797,8 @@
"required": true
},
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "index of the issue",
"name": "index",
"in": "path",
@ -10807,7 +10849,8 @@
"required": true
},
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "index of the issue",
"name": "index",
"in": "path",
@ -12340,6 +12383,17 @@
"in": "path",
"required": true
},
{
"enum": [
"mostissues",
"leastissues",
"reversealphabetically"
],
"type": "string",
"description": "Specifies the sorting method: mostissues, leastissues, or reversealphabetically.",
"name": "sort",
"in": "query"
},
{
"type": "integer",
"description": "page number of results to return (1-based)",
@ -12766,7 +12820,8 @@
"required": true
},
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "the milestone to get, identified by ID and if not available by name",
"name": "id",
"in": "path",
@ -12804,7 +12859,8 @@
"required": true
},
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "the milestone to delete, identified by ID and if not available by name",
"name": "id",
"in": "path",
@ -12848,7 +12904,8 @@
"required": true
},
{
"type": "string",
"type": "integer",
"format": "int64",
"description": "the milestone to edit, identified by ID and if not available by name",
"name": "id",
"in": "path",
@ -13071,7 +13128,7 @@
"required": true
},
{
"type": "string",
"type": "boolean",
"description": "If true, mark all notifications on this repo. Default value is false",
"name": "all",
"in": "query"
@ -16258,6 +16315,7 @@
},
{
"type": "integer",
"format": "int64",
"description": "id of the tag protect to get",
"name": "id",
"in": "path",
@ -16299,6 +16357,7 @@
},
{
"type": "integer",
"format": "int64",
"description": "id of protected tag",
"name": "id",
"in": "path",
@ -16343,6 +16402,7 @@
},
{
"type": "integer",
"format": "int64",
"description": "id of protected tag",
"name": "id",
"in": "path",
@ -17756,6 +17816,7 @@
"parameters": [
{
"type": "integer",
"format": "int64",
"description": "id of the team to edit",
"name": "id",
"in": "path",
@ -18187,7 +18248,19 @@
],
"responses": {
"200": {
"$ref": "#/responses/TopicListResponse"
"description": "SearchResults of a successful search",
"schema": {
"type": "object",
"title": "TopicSearchResults",
"properties": {
"topics": {
"type": "array",
"items": {
"$ref": "#/definitions/TopicResponse"
}
}
}
}
},
"403": {
"$ref": "#/responses/forbidden"
@ -19151,6 +19224,15 @@
],
"summary": "Verify a GPG key",
"operationId": "userVerifyGPGKey",
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"$ref": "#/definitions/VerifyGPGKeyOption"
}
}
],
"responses": {
"201": {
"$ref": "#/responses/GPGKey"
@ -19825,9 +19907,21 @@
],
"summary": "Check if the authenticated user is over quota for a given subject",
"operationId": "userCheckQuota",
"parameters": [
{
"type": "string",
"description": "subject of the quota",
"name": "subject",
"in": "query",
"required": true
}
],
"responses": {
"200": {
"$ref": "#/responses/boolean"
"description": "Returns true if the action is accepted.",
"schema": {
"type": "boolean"
}
},
"401": {
"$ref": "#/responses/unauthorized"
@ -20452,6 +20546,7 @@
"description": "SearchResults of a successful search",
"schema": {
"type": "object",
"title": "UserSearchResults",
"properties": {
"data": {
"type": "array",
@ -27547,6 +27642,17 @@
},
"x-go-package": "forgejo.org/modules/structs"
},
"RegistrationToken": {
"description": "RegistrationToken is a string used to register a runner with a server",
"type": "object",
"properties": {
"token": {
"type": "string",
"x-go-name": "Token"
}
},
"x-go-package": "forgejo.org/routers/api/v1/shared"
},
"Release": {
"description": "Release represents a repository release",
"type": "object",
@ -28972,6 +29078,25 @@
},
"x-go-package": "forgejo.org/modules/structs"
},
"VerifyGPGKeyOption": {
"description": "VerifyGPGKeyOption options verifies user GPG key",
"type": "object",
"required": [
"key_id"
],
"properties": {
"armored_signature": {
"type": "string",
"x-go-name": "Signature"
},
"key_id": {
"description": "An Signature for a GPG key token",
"type": "string",
"x-go-name": "KeyID"
}
},
"x-go-package": "forgejo.org/modules/structs"
},
"WatchInfo": {
"description": "WatchInfo represents an API watch status of one repository",
"type": "object",
@ -29891,10 +30016,8 @@
},
"RegistrationToken": {
"description": "RegistrationToken is a string used to register a runner with a server",
"headers": {
"token": {
"type": "string"
}
"schema": {
"$ref": "#/definitions/RegistrationToken"
}
},
"Release": {
@ -30014,10 +30137,7 @@
"SyncForkInfo": {
"description": "SyncForkInfo",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/SyncForkInfo"
}
"$ref": "#/definitions/SyncForkInfo"
}
},
"Tag": {