From 9aa197b196fdbbb5787494dd87c490ce23010866 Mon Sep 17 00:00:00 2001 From: kolaente Date: Fri, 24 Jan 2025 14:20:07 +0100 Subject: [PATCH] fix: swagger docs --- pkg/models/task_collection.go | 4 +-- pkg/models/task_comments.go | 2 +- pkg/models/tasks.go | 4 +-- pkg/swagger/docs.go | 47 ++++++++++++++++++++++++++----- pkg/swagger/swagger.json | 42 ++++++++++++++++++++++++--- pkg/swagger/swagger.yaml | 53 +++++++++++++++++++++++++++++++---- 6 files changed, 130 insertions(+), 22 deletions(-) diff --git a/pkg/models/task_collection.go b/pkg/models/task_collection.go index 1ff8ce115..c42d7b452 100644 --- a/pkg/models/task_collection.go +++ b/pkg/models/task_collection.go @@ -54,7 +54,7 @@ type TaskCollection struct { // pagination limit being returned, but all subtasks will be present in the response. // If set to `buckets`, the buckets of each task will be present in the response. // If set to `reactions`, the reactions of each task will be present in the response. - // If set to `comments`, the first 25 comments of each task will be present in the response. + // If set to `comments`, the first 50 comments of each task will be present in the response. // You can set this multiple times with different values. Expand []TaskCollectionExpandable `query:"expand" json:"-"` @@ -247,7 +247,7 @@ func getFilterValueForBucketFilter(filter string, view *ProjectView) (newFilter // @Param filter query string false "The filter query to match tasks by. Check out https://vikunja.io/docs/filters for a full explanation of the feature." // @Param filter_timezone query string false "The time zone which should be used for date match (statements like "now" resolve to different actual times)" // @Param filter_include_nulls query string false "If set to true the result will include filtered fields whose value is set to `null`. Available values are `true` or `false`. Defaults to `false`." -// @Param expand query string false "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to `buckets`, the buckets of each task will be present in the response. If set to `reactions`, the reactions of each task will be present in the response. If set to `comments`, the first 25 comments of each task will be present in the response. You can set this multiple times with different values. +// @Param expand query array false "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to `buckets`, the buckets of each task will be present in the response. If set to `reactions`, the reactions of each task will be present in the response. If set to `comments`, the first 50 comments of each task will be present in the response. You can set this multiple times with different values." // @Security JWTKeyAuth // @Success 200 {array} models.Task "The tasks" // @Failure 500 {object} models.Message "Internal error" diff --git a/pkg/models/task_comments.go b/pkg/models/task_comments.go index 14b9ea318..21b92b034 100644 --- a/pkg/models/task_comments.go +++ b/pkg/models/task_comments.go @@ -256,7 +256,7 @@ func (tc *TaskComment) ReadAll(s *xorm.Session, auth web.Auth, search string, pa } func addCommentsToTasks(s *xorm.Session, taskIDs []int64, taskMap map[int64]*Task) (err error) { - comments, _, _, err := getAllCommentsForTasksWithoutPermissionCheck(s, taskIDs, "", 0, 0) + comments, _, _, err := getAllCommentsForTasksWithoutPermissionCheck(s, taskIDs, "", 0, 50) if err != nil { return err } diff --git a/pkg/models/tasks.go b/pkg/models/tasks.go index 4f8fff650..238bb8baa 100644 --- a/pkg/models/tasks.go +++ b/pkg/models/tasks.go @@ -211,7 +211,7 @@ type taskSearchOptions struct { // @Param filter query string false "The filter query to match tasks by. Check out https://vikunja.io/docs/filters for a full explanation of the feature." // @Param filter_timezone query string false "The time zone which should be used for date match (statements like "now" resolve to different actual times)" // @Param filter_include_nulls query string false "If set to true the result will include filtered fields whose value is set to `null`. Available values are `true` or `false`. Defaults to `false`." -// @Param expand query string false "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to `buckets`, the buckets of each task will be present in the response. If set to `reactions`, the reactions of each task will be present in the response. If set to `comments`, the first 25 comments of each task will be present in the response. You can set this multiple times with different values. +// @Param expand query array false "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to `buckets`, the buckets of each task will be present in the response. If set to `reactions`, the reactions of each task will be present in the response. If set to `comments`, the first 50 comments of each task will be present in the response. You can set this multiple times with different values." // @Security JWTKeyAuth // @Success 200 {array} models.Task "The tasks" // @Failure 500 {object} models.Message "Internal error" @@ -1691,7 +1691,7 @@ func (t *Task) Delete(s *xorm.Session, a web.Auth) (err error) { // @Accept json // @Produce json // @Param id path int true "The task ID" -// @Param expand query string false "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to `buckets`, the buckets of each task will be present in the response. If set to `reactions`, the reactions of each task will be present in the response. You can set this multiple times with different values. +// @Param expand query array false "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to `buckets`, the buckets of each task will be present in the response. If set to `reactions`, the reactions of each task will be present in the response. If set to `comments`, the first 50 comments of each task will be present in the response. You can set this multiple times with different values." // @Security JWTKeyAuth // @Success 200 {object} models.Task "The task" // @Failure 404 {object} models.Message "Task not found" diff --git a/pkg/swagger/docs.go b/pkg/swagger/docs.go index 7319655f9..10e2a22f1 100644 --- a/pkg/swagger/docs.go +++ b/pkg/swagger/docs.go @@ -1,4 +1,5 @@ -// Package swagger Code generated by swaggo/swag. DO NOT EDIT +// Code generated by swaggo/swag. DO NOT EDIT. + package swagger import "github.com/swaggo/swag" @@ -2505,8 +2506,8 @@ const docTemplate = `{ "in": "query" }, { - "type": "string", - "description": "If set to ` + "`" + `subtasks` + "`" + `, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. You can only set this to ` + "`" + `subtasks` + "`" + `.", + "type": "array", + "description": "If set to ` + "`" + `subtasks` + "`" + `, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to ` + "`" + `buckets` + "`" + `, the buckets of each task will be present in the response. If set to ` + "`" + `reactions` + "`" + `, the reactions of each task will be present in the response. If set to ` + "`" + `comments` + "`" + `, the first 50 comments of each task will be present in the response. You can set this multiple times with different values.", "name": "expand", "in": "query" } @@ -4131,8 +4132,8 @@ const docTemplate = `{ "in": "query" }, { - "type": "string", - "description": "If set to ` + "`" + `subtasks` + "`" + `, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. You can only set this to ` + "`" + `subtasks` + "`" + `.", + "type": "array", + "description": "If set to ` + "`" + `subtasks` + "`" + `, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to ` + "`" + `buckets` + "`" + `, the buckets of each task will be present in the response. If set to ` + "`" + `reactions` + "`" + `, the reactions of each task will be present in the response. If set to ` + "`" + `comments` + "`" + `, the first 50 comments of each task will be present in the response. You can set this multiple times with different values.", "name": "expand", "in": "query" } @@ -4238,6 +4239,12 @@ const docTemplate = `{ "name": "id", "in": "path", "required": true + }, + { + "type": "array", + "description": "If set to ` + "`" + `subtasks` + "`" + `, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to ` + "`" + `buckets` + "`" + `, the buckets of each task will be present in the response. If set to ` + "`" + `reactions` + "`" + `, the reactions of each task will be present in the response. If set to ` + "`" + `comments` + "`" + `, the first 50 comments of each task will be present in the response. You can set this multiple times with different values.", + "name": "expand", + "in": "query" } ], "responses": { @@ -7926,6 +7933,20 @@ const docTemplate = `{ "description": "The bucket id. Will only be populated when the task is accessed via a view with buckets.\nCan be used to move a task between buckets. In that case, the new bucket must be in the same view as the old one.", "type": "integer" }, + "buckets": { + "description": "All buckets across all views this task is part of. Only present when fetching tasks with the ` + "`" + `expand` + "`" + ` parameter set to ` + "`" + `buckets` + "`" + `.", + "type": "array", + "items": { + "$ref": "#/definitions/models.Bucket" + } + }, + "comments": { + "description": "All comments of this task. Only present when fetching tasks with the ` + "`" + `expand` + "`" + ` parameter set to ` + "`" + `comments` + "`" + `.", + "type": "array", + "items": { + "$ref": "#/definitions/models.TaskComment" + } + }, "cover_image_attachment_id": { "description": "If this task has a cover image, the field will return the id of the attachment that is the cover image.", "type": "integer" @@ -8665,6 +8686,20 @@ const docTemplate = `{ "description": "The bucket id. Will only be populated when the task is accessed via a view with buckets.\nCan be used to move a task between buckets. In that case, the new bucket must be in the same view as the old one.", "type": "integer" }, + "buckets": { + "description": "All buckets across all views this task is part of. Only present when fetching tasks with the ` + "`" + `expand` + "`" + ` parameter set to ` + "`" + `buckets` + "`" + `.", + "type": "array", + "items": { + "$ref": "#/definitions/models.Bucket" + } + }, + "comments": { + "description": "All comments of this task. Only present when fetching tasks with the ` + "`" + `expand` + "`" + ` parameter set to ` + "`" + `comments` + "`" + `.", + "type": "array", + "items": { + "$ref": "#/definitions/models.TaskComment" + } + }, "cover_image_attachment_id": { "description": "If this task has a cover image, the field will return the id of the attachment that is the cover image.", "type": "integer" @@ -9788,8 +9823,6 @@ var SwaggerInfo = &swag.Spec{ Description: "# Pagination\nEvery endpoint capable of pagination will return two headers:\n* `x-pagination-total-pages`: The total number of available pages for this request\n* `x-pagination-result-count`: The number of items returned for this request.\n# Rights\nAll endpoints which return a single item (project, task, etc.) - no array - will also return a `x-max-right` header with the max right the user has on this item as an int where `0` is `Read Only`, `1` is `Read & Write` and `2` is `Admin`.\nThis can be used to show or hide ui elements based on the rights the user has.\n# Errors\nAll errors have an error code and a human-readable error message in addition to the http status code. You should always check for the status code in the response, not only the http status code.\nDue to limitations in the swagger library we're using for this document, only one error per http status code is documented here. Make sure to check the [error docs](https://vikunja.io/docs/errors/) in Vikunja's documentation for a full list of available error codes.\n# Authorization\n**JWT-Auth:** Main authorization method, used for most of the requests. Needs `Authorization: Bearer `-header to authenticate successfully.\n\n**API Token:** You can create scoped API tokens for your user and use the token to make authenticated requests in the context of that user. The token must be provided via an `Authorization: Bearer ` header, similar to jwt auth. See the documentation for the `api` group to manage token creation and revocation.\n\n**BasicAuth:** Only used when requesting tasks via CalDAV.\n", InfoInstanceName: "swagger", SwaggerTemplate: docTemplate, - LeftDelim: "{{", - RightDelim: "}}", } func init() { diff --git a/pkg/swagger/swagger.json b/pkg/swagger/swagger.json index 6564726f2..b002f3992 100644 --- a/pkg/swagger/swagger.json +++ b/pkg/swagger/swagger.json @@ -2497,8 +2497,8 @@ "in": "query" }, { - "type": "string", - "description": "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. You can only set this to `subtasks`.", + "type": "array", + "description": "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to `buckets`, the buckets of each task will be present in the response. If set to `reactions`, the reactions of each task will be present in the response. If set to `comments`, the first 50 comments of each task will be present in the response. You can set this multiple times with different values.", "name": "expand", "in": "query" } @@ -4123,8 +4123,8 @@ "in": "query" }, { - "type": "string", - "description": "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. You can only set this to `subtasks`.", + "type": "array", + "description": "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to `buckets`, the buckets of each task will be present in the response. If set to `reactions`, the reactions of each task will be present in the response. If set to `comments`, the first 50 comments of each task will be present in the response. You can set this multiple times with different values.", "name": "expand", "in": "query" } @@ -4230,6 +4230,12 @@ "name": "id", "in": "path", "required": true + }, + { + "type": "array", + "description": "If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, but all subtasks will be present in the response. If set to `buckets`, the buckets of each task will be present in the response. If set to `reactions`, the reactions of each task will be present in the response. If set to `comments`, the first 50 comments of each task will be present in the response. You can set this multiple times with different values.", + "name": "expand", + "in": "query" } ], "responses": { @@ -7918,6 +7924,20 @@ "description": "The bucket id. Will only be populated when the task is accessed via a view with buckets.\nCan be used to move a task between buckets. In that case, the new bucket must be in the same view as the old one.", "type": "integer" }, + "buckets": { + "description": "All buckets across all views this task is part of. Only present when fetching tasks with the `expand` parameter set to `buckets`.", + "type": "array", + "items": { + "$ref": "#/definitions/models.Bucket" + } + }, + "comments": { + "description": "All comments of this task. Only present when fetching tasks with the `expand` parameter set to `comments`.", + "type": "array", + "items": { + "$ref": "#/definitions/models.TaskComment" + } + }, "cover_image_attachment_id": { "description": "If this task has a cover image, the field will return the id of the attachment that is the cover image.", "type": "integer" @@ -8657,6 +8677,20 @@ "description": "The bucket id. Will only be populated when the task is accessed via a view with buckets.\nCan be used to move a task between buckets. In that case, the new bucket must be in the same view as the old one.", "type": "integer" }, + "buckets": { + "description": "All buckets across all views this task is part of. Only present when fetching tasks with the `expand` parameter set to `buckets`.", + "type": "array", + "items": { + "$ref": "#/definitions/models.Bucket" + } + }, + "comments": { + "description": "All comments of this task. Only present when fetching tasks with the `expand` parameter set to `comments`.", + "type": "array", + "items": { + "$ref": "#/definitions/models.TaskComment" + } + }, "cover_image_attachment_id": { "description": "If this task has a cover image, the field will return the id of the attachment that is the cover image.", "type": "integer" diff --git a/pkg/swagger/swagger.yaml b/pkg/swagger/swagger.yaml index c0c4eb7e8..27872089e 100644 --- a/pkg/swagger/swagger.yaml +++ b/pkg/swagger/swagger.yaml @@ -167,6 +167,18 @@ definitions: The bucket id. Will only be populated when the task is accessed via a view with buckets. Can be used to move a task between buckets. In that case, the new bucket must be in the same view as the old one. type: integer + buckets: + description: All buckets across all views this task is part of. Only present + when fetching tasks with the `expand` parameter set to `buckets`. + items: + $ref: '#/definitions/models.Bucket' + type: array + comments: + description: All comments of this task. Only present when fetching tasks with + the `expand` parameter set to `comments`. + items: + $ref: '#/definitions/models.TaskComment' + type: array cover_image_attachment_id: description: If this task has a cover image, the field will return the id of the attachment that is the cover image. @@ -742,6 +754,18 @@ definitions: The bucket id. Will only be populated when the task is accessed via a view with buckets. Can be used to move a task between buckets. In that case, the new bucket must be in the same view as the old one. type: integer + buckets: + description: All buckets across all views this task is part of. Only present + when fetching tasks with the `expand` parameter set to `buckets`. + items: + $ref: '#/definitions/models.Bucket' + type: array + comments: + description: All comments of this task. Only present when fetching tasks with + the `expand` parameter set to `comments`. + items: + $ref: '#/definitions/models.TaskComment' + type: array cover_image_attachment_id: description: If this task has a cover image, the field will return the id of the attachment that is the cover image. @@ -3400,11 +3424,14 @@ paths: - description: If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, - but all subtasks will be present in the response. You can only set this - to `subtasks`. + but all subtasks will be present in the response. If set to `buckets`, the + buckets of each task will be present in the response. If set to `reactions`, + the reactions of each task will be present in the response. If set to `comments`, + the first 50 comments of each task will be present in the response. You + can set this multiple times with different values. in: query name: expand - type: string + type: array produces: - application/json responses: @@ -4477,6 +4504,17 @@ paths: name: id required: true type: integer + - description: If set to `subtasks`, Vikunja will fetch only tasks which do + not have subtasks and then in a second step, will fetch all of these subtasks. + This may result in more tasks than the pagination limit being returned, + but all subtasks will be present in the response. If set to `buckets`, the + buckets of each task will be present in the response. If set to `reactions`, + the reactions of each task will be present in the response. If set to `comments`, + the first 50 comments of each task will be present in the response. You + can set this multiple times with different values. + in: query + name: expand + type: array produces: - application/json responses: @@ -5403,11 +5441,14 @@ paths: - description: If set to `subtasks`, Vikunja will fetch only tasks which do not have subtasks and then in a second step, will fetch all of these subtasks. This may result in more tasks than the pagination limit being returned, - but all subtasks will be present in the response. You can only set this - to `subtasks`. + but all subtasks will be present in the response. If set to `buckets`, the + buckets of each task will be present in the response. If set to `reactions`, + the reactions of each task will be present in the response. If set to `comments`, + the first 50 comments of each task will be present in the response. You + can set this multiple times with different values. in: query name: expand - type: string + type: array produces: - application/json responses: