vikunja
/
vikunja
6
43
Fork 72
Code Issues 150 Pull Requests 19 Packages Releases 32 Activity

feat(reactions): add swagger docs

This commit is contained in:
kolaente 2024-03-11 22:34:28 +01:00
parent 389ea6258d
commit 5c846ea990
Signed by: konrad
GPG Key ID: F40E70337AB24C9B
4 changed files with 620 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
pkg/models/reaction.go
View File

@ -33,16 +33,16 @@ const (
type Reaction struct {
// The unique numeric id of this reaction
ID int64 `xorm:"autoincr not null unique pk" json:"id" param:"reaction"`
ID int64 `xorm:"autoincr not null unique pk" json:"-" param:"reaction"`
// The user who reacted
User *user.User `xorm:"-" json:"user" valid:"-"`
UserID int64 `xorm:"bigint not null INDEX" json:"-"`
// The id of the entity you're reacting to
EntityID int64 `xorm:"bigint not null INDEX" json:"entity_id" param:"entityid"`
EntityID int64 `xorm:"bigint not null INDEX" json:"-" param:"entityid"`
// The entity kind which you're reacting to. Can be 0 for task, 1 for comment.
EntityKind ReactionKind `xorm:"bigint not null INDEX" json:"entity_kind"`
EntityKind ReactionKind `xorm:"bigint not null INDEX" json:"-"`
EntityKindString string `xorm:"-" json:"-" param:"entitykind"`
// The actual reaction. This can be any valid utf character or text, up to a length of 20.
@ -59,6 +59,21 @@ func (*Reaction) TableName() string {
return "reactions"
}
type ReactionMap map[string][]*user.User
// ReadAll gets all reactions for an entity
// @Summary Get all reactions for an entity
// @Description Returns all reactions for an entity
// @tags task
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param id path int true "Entity ID"
// @Param kind path int true "The kind of the entity. Can be either `tasks` or `comments` for task comments"
// @Success 200 {array} models.ReactionMap "The reactions"
// @Failure 403 {object} web.HTTPError "The user does not have access to the entity"
// @Failure 500 {object} models.Message "Internal error"
// @Router /{kind}/{id}/reactions [get]
func (r *Reaction) ReadAll(s *xorm.Session, _ web.Auth, _ string, _ int, _ int) (result interface{}, resultCount int, numberOfTotalItems int64, err error) {
reactions := []*Reaction{}
err = s.Where("entity_id = ? AND entity_kind = ?", r.EntityID, r.EntityKind).Find(&reactions)
@ -77,7 +92,7 @@ func (r *Reaction) ReadAll(s *xorm.Session, _ web.Auth, _ string, _ int, _ int)
return
}
reactionMap := make(map[string][]*user.User)
reactionMap := make(ReactionMap)
for _, reaction := range reactions {
if _, has := reactionMap[reaction.Value]; !has {
reactionMap[reaction.Value] = []*user.User{}
@ -89,14 +104,41 @@ func (r *Reaction) ReadAll(s *xorm.Session, _ web.Auth, _ string, _ int, _ int)
return reactionMap, len(reactionMap), int64(len(reactions)), nil
}
// Delete removes the user's own reaction
// @Summary Removes the user's reaction
// @Description Removes the reaction of that user on that entity.
// @tags task
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param id path int true "Entity ID"
// @Param kind path int true "The kind of the entity. Can be either `tasks` or `comments` for task comments"
// @Param project body models.Reaction true "The reaction you want to add to the entity."
// @Success 200 {object} models.Message "The reaction was successfully removed."
// @Failure 403 {object} web.HTTPError "The user does not have access to the entity"
// @Failure 500 {object} models.Message "Internal error"
// @Router /{kind}/{id}/reactions [delete]
func (r *Reaction) Delete(s *xorm.Session, a web.Auth) (err error) {
r.UserID = a.GetID()
_, err = s.Where("user_id = ? AND entity_id = ? AND entity_kind = ?", r.UserID, r.EntityID, r.EntityKind).
_, err = s.Where("user_id = ? AND entity_id = ? AND entity_kind = ? AND value = ?", r.UserID, r.EntityID, r.EntityKind, r.Value).
Delete(&Reaction{})
return
}
// Create adds a new reaction to an entity
// @Summary Add a reaction to an entity
// @tags task
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param id path int true "Entity ID"
// @Param kind path int true "The kind of the entity. Can be either `tasks` or `comments` for task comments"
// @Param project body models.Reaction true "The reaction you want to add to the entity."
// @Success 200 {object} models.Reaction "The created reaction"
// @Failure 403 {object} web.HTTPError "The user does not have access to the entity"
// @Failure 500 {object} models.Message "Internal error"
// @Router /{kind}/{id}/reactions [put]
func (r *Reaction) Create(s *xorm.Session, a web.Auth) (err error) {
r.UserID = a.GetID()

219
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"
@ -7042,6 +7043,190 @@ const docTemplate = `{
}
}
},
"/{kind}/{id}/reactions": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns all reactions for an entity",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"task"
],
"summary": "Get all reactions for an entity",
"parameters": [
{
"type": "integer",
"description": "Entity ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "The kind of the entity. Can be either ` + "`" + `tasks` + "`" + ` or ` + "`" + `comments` + "`" + ` for task comments",
"name": "kind",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The reactions",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/models.ReactionMap"
}
}
},
"403": {
"description": "The user does not have access to the entity",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"put": {
"security": [
{
"JWTKeyAuth": []
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"task"
],
"summary": "Add a reaction to an entity",
"parameters": [
{
"type": "integer",
"description": "Entity ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "The kind of the entity. Can be either ` + "`" + `tasks` + "`" + ` or ` + "`" + `comments` + "`" + ` for task comments",
"name": "kind",
"in": "path",
"required": true
},
{
"description": "The reaction you want to add to the entity.",
"name": "project",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.Reaction"
}
}
],
"responses": {
"200": {
"description": "The created reaction",
"schema": {
"$ref": "#/definitions/models.Reaction"
}
},
"403": {
"description": "The user does not have access to the entity",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"delete": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Removes the reaction of that user on that entity.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"task"
],
"summary": "Removes the user's reaction",
"parameters": [
{
"type": "integer",
"description": "Entity ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "The kind of the entity. Can be either ` + "`" + `tasks` + "`" + ` or ` + "`" + `comments` + "`" + ` for task comments",
"name": "kind",
"in": "path",
"required": true
},
{
"description": "The reaction you want to add to the entity.",
"name": "project",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.Reaction"
}
}
],
"responses": {
"200": {
"description": "The reaction was successfully removed.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"403": {
"description": "The user does not have access to the entity",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/{username}/avatar": {
"get": {
"description": "Returns the user avatar as image.",
@ -7754,6 +7939,36 @@ const docTemplate = `{
}
}
},
"models.Reaction": {
"type": "object",
"properties": {
"created": {
"description": "A timestamp when this reaction was created. You cannot change this value.",
"type": "string"
},
"user": {
"description": "The user who reacted",
"allOf": [
{
"$ref": "#/definitions/user.User"
}
]
},
"value": {
"description": "The actual reaction. This can be any valid utf character or text, up to a length of 20.",
"type": "string"
}
}
},
"models.ReactionMap": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/definitions/user.User"
}
}
},
"models.RelatedTaskMap": {
"type": "object",
"additionalProperties": {
@ -8975,8 +9190,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() {

214
pkg/swagger/swagger.json
View File

@ -7034,6 +7034,190 @@
}
}
},
"/{kind}/{id}/reactions": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns all reactions for an entity",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"task"
],
"summary": "Get all reactions for an entity",
"parameters": [
{
"type": "integer",
"description": "Entity ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "The kind of the entity. Can be either `tasks` or `comments` for task comments",
"name": "kind",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The reactions",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/models.ReactionMap"
}
}
},
"403": {
"description": "The user does not have access to the entity",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"put": {
"security": [
{
"JWTKeyAuth": []
}
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"task"
],
"summary": "Add a reaction to an entity",
"parameters": [
{
"type": "integer",
"description": "Entity ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "The kind of the entity. Can be either `tasks` or `comments` for task comments",
"name": "kind",
"in": "path",
"required": true
},
{
"description": "The reaction you want to add to the entity.",
"name": "project",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.Reaction"
}
}
],
"responses": {
"200": {
"description": "The created reaction",
"schema": {
"$ref": "#/definitions/models.Reaction"
}
},
"403": {
"description": "The user does not have access to the entity",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"delete": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Removes the reaction of that user on that entity.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"task"
],
"summary": "Removes the user's reaction",
"parameters": [
{
"type": "integer",
"description": "Entity ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "The kind of the entity. Can be either `tasks` or `comments` for task comments",
"name": "kind",
"in": "path",
"required": true
},
{
"description": "The reaction you want to add to the entity.",
"name": "project",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.Reaction"
}
}
],
"responses": {
"200": {
"description": "The reaction was successfully removed.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"403": {
"description": "The user does not have access to the entity",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/{username}/avatar": {
"get": {
"description": "Returns the user avatar as image.",
@ -7746,6 +7930,36 @@
}
}
},
"models.Reaction": {
"type": "object",
"properties": {
"created": {
"description": "A timestamp when this reaction was created. You cannot change this value.",
"type": "string"
},
"user": {
"description": "The user who reacted",
"allOf": [
{
"$ref": "#/definitions/user.User"
}
]
},
"value": {
"description": "The actual reaction. This can be any valid utf character or text, up to a length of 20.",
"type": "string"
}
}
},
"models.ReactionMap": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"$ref": "#/definitions/user.User"
}
}
},
"models.RelatedTaskMap": {
"type": "object",
"additionalProperties": {

143
pkg/swagger/swagger.yaml
View File

@ -509,6 +509,27 @@ definitions:
description: The username.
type: string
type: object
models.Reaction:
properties:
created:
description: A timestamp when this reaction was created. You cannot change
this value.
type: string
user:
allOf:
- $ref: '#/definitions/user.User'
description: The user who reacted
value:
description: The actual reaction. This can be any valid utf character or text,
up to a length of 20.
type: string
type: object
models.ReactionMap:
additionalProperties:
items:
$ref: '#/definitions/user.User'
type: array
type: object
models.RelatedTaskMap:
additionalProperties:
items:
@ -1439,6 +1460,128 @@ info:
url: https://code.vikunja.io/api/src/branch/main/LICENSE
title: Vikunja API
paths:
/{kind}/{id}/reactions:
delete:
consumes:
- application/json
description: Removes the reaction of that user on that entity.
parameters:
- description: Entity ID
in: path
name: id
required: true
type: integer
- description: The kind of the entity. Can be either `tasks` or `comments` for
task comments
in: path
name: kind
required: true
type: integer
- description: The reaction you want to add to the entity.
in: body
name: project
required: true
schema:
$ref: '#/definitions/models.Reaction'
produces:
- application/json
responses:
"200":
description: The reaction was successfully removed.
schema:
$ref: '#/definitions/models.Message'
"403":
description: The user does not have access to the entity
schema:
$ref: '#/definitions/web.HTTPError'
"500":
description: Internal error
schema:
$ref: '#/definitions/models.Message'
security:
- JWTKeyAuth: []
summary: Removes the user's reaction
tags:
- task
get:
consumes:
- application/json
description: Returns all reactions for an entity
parameters:
- description: Entity ID
in: path
name: id
required: true
type: integer
- description: The kind of the entity. Can be either `tasks` or `comments` for
task comments
in: path
name: kind
required: true
type: integer
produces:
- application/json
responses:
"200":
description: The reactions
schema:
items:
$ref: '#/definitions/models.ReactionMap'
type: array
"403":
description: The user does not have access to the entity
schema:
$ref: '#/definitions/web.HTTPError'
"500":
description: Internal error
schema:
$ref: '#/definitions/models.Message'
security:
- JWTKeyAuth: []
summary: Get all reactions for an entity
tags:
- task
put:
consumes:
- application/json
parameters:
- description: Entity ID
in: path
name: id
required: true
type: integer
- description: The kind of the entity. Can be either `tasks` or `comments` for
task comments
in: path
name: kind
required: true
type: integer
- description: The reaction you want to add to the entity.
in: body
name: project
required: true
schema:
$ref: '#/definitions/models.Reaction'
produces:
- application/json
responses:
"200":
description: The created reaction
schema:
$ref: '#/definitions/models.Reaction'
"403":
description: The user does not have access to the entity
schema:
$ref: '#/definitions/web.HTTPError'
"500":
description: Internal error
schema:
$ref: '#/definitions/models.Message'
security:
- JWTKeyAuth: []
summary: Add a reaction to an entity
tags:
- task
/{username}/avatar:
get:
description: Returns the user avatar as image.