clone/vikunja
1
0
Fork 0
mirror of https://github.com/go-vikunja/vikunja.git synced 2026-02-01 22:47:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: swagger docs

Browse Source
This commit is contained in:
kolaente
2025-01-24 14:20:07 +01:00
parent cd304b9e4e
commit 9aa197b196
6 changed files with 130 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
pkg/models/task_collection.go
View File

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

2
pkg/models/task_comments.go
View File

@@ -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
}

4
pkg/models/tasks.go
View File

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

47
pkg/swagger/docs.go
View File

@@ -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 <jwt-token>`-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 <token>` 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<!-- ReDoc-Inject: <security-definitions> -->",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
LeftDelim: "{{",
RightDelim: "}}",
}
func init() {

42
pkg/swagger/swagger.json
View File

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

53
pkg/swagger/swagger.yaml
View File

@@ -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: