mirror of
https://github.com/photoprism/photoprism.git
synced 2025-12-12 00:34:13 +01:00
API: Add Swagger annotations #2132
This commit is contained in:
graciousgrey
@@ -14,7 +14,13 @@ import (
|
||||
|
||||
// GetSettings returns the user app settings as JSON.
|
||||
//
|
||||
// GET /api/v1/settings
|
||||
// @Summary returns the user app settings as JSON
|
||||
// @Id GetSettings
|
||||
// @Tags Settings
|
||||
// @Produce json
|
||||
// @Success 200 {object} customize.Settings
|
||||
// @Failure 401,403,404 {object} i18n.Response
|
||||
// @Router /api/v1/settings [get]
|
||||
func GetSettings(router *gin.RouterGroup) {
|
||||
router.GET("/settings", func(c *gin.Context) {
|
||||
s := AuthAny(c, acl.ResourceSettings, acl.Permissions{acl.AccessAll, acl.AccessOwn})
|
||||
@@ -35,10 +41,16 @@ func GetSettings(router *gin.RouterGroup) {
|
||||
})
|
||||
}
|
||||
|
||||
// SaveSettings saved the user app settings.
|
||||
// SaveSettings saves the user app settings.
|
||||
//
|
||||
// @Tags Settings
|
||||
// @Router /api/v1/settings [post]
|
||||
// @Summary saves the user app settings
|
||||
// @Id SaveSettings
|
||||
// @Tags Settings
|
||||
// @Produce json
|
||||
// @Success 200 {object} customize.Settings
|
||||
// @Failure 400,401,403,404,500 {object} i18n.Response
|
||||
// @Param settings body customize.Settings true "user settings"
|
||||
// @Router /api/v1/settings [post]
|
||||
func SaveSettings(router *gin.RouterGroup) {
|
||||
router.POST("/settings", func(c *gin.Context) {
|
||||
s := AuthAny(c, acl.ResourceSettings, acl.Permissions{acl.ActionView, acl.ActionUpdate, acl.ActionManage})
|
||||
|
||||
@@ -14,7 +14,16 @@ import (
|
||||
|
||||
// GetErrors searches the error logs and returns the results as JSON.
|
||||
//
|
||||
// GET /api/v1/errors
|
||||
// @Summary searches the error logs and returns the results as JSON
|
||||
// @Id GetErrors
|
||||
// @Tags Errors
|
||||
// @Produce json
|
||||
// @Success 200 {object} entity.Error
|
||||
// @Failure 401,403,429,400 {object} i18n.Response
|
||||
// @Param count query int true "maximum number of results" minimum(1) maximum(100000)
|
||||
// @Param offset query int false "search result offset" minimum(0) maximum(100000)
|
||||
// @Param q query string false "search query"
|
||||
// @Router /api/v1/errors [get]
|
||||
func GetErrors(router *gin.RouterGroup) {
|
||||
router.GET("/errors", func(c *gin.Context) {
|
||||
// Check authentication and authorization.
|
||||
@@ -43,7 +52,12 @@ func GetErrors(router *gin.RouterGroup) {
|
||||
|
||||
// DeleteErrors removes all entries from the error logs.
|
||||
//
|
||||
// DELETE /api/v1/errors
|
||||
// @Summary removes all entries from the error logs
|
||||
// @Id Delete Errors
|
||||
// @Tags Errors
|
||||
// @Produce json
|
||||
// @Failure 401,403,429,500 {object} i18n.Response
|
||||
// @Router /api/v1/errors [delete]
|
||||
func DeleteErrors(router *gin.RouterGroup) {
|
||||
router.DELETE("/errors", func(c *gin.Context) {
|
||||
conf := get.Config()
|
||||
|
||||
@@ -17,7 +17,14 @@ import (
|
||||
|
||||
// GetFace returns a face as JSON.
|
||||
//
|
||||
// GET /api/v1/faces/:id
|
||||
// @Summary returns a face as JSON
|
||||
// @Id GetFace
|
||||
// @Tags Faces
|
||||
// @Produce json
|
||||
// @Success 200 {object} entity.Face
|
||||
// @Failure 401,403,404,429 {object} i18n.Response
|
||||
// @Param id path string true "face id"
|
||||
// @Router /api/v1/faces/{id} [get]
|
||||
func GetFace(router *gin.RouterGroup) {
|
||||
router.GET("/faces/:id", func(c *gin.Context) {
|
||||
s := Auth(c, acl.ResourcePeople, acl.ActionView)
|
||||
@@ -40,7 +47,15 @@ func GetFace(router *gin.RouterGroup) {
|
||||
|
||||
// UpdateFace updates face properties.
|
||||
//
|
||||
// PUT /api/v1/faces/:id
|
||||
// @Summary updates face properties
|
||||
// @Id UpdateFace
|
||||
// @Tags Faces
|
||||
// @Produce json
|
||||
// @Success 200 {object} entity.Face
|
||||
// @Failure 400,401,403,404,429,500 {object} i18n.Response
|
||||
// @Param id path string true "face id"
|
||||
// @Param face body form.Face true "properties to be updated"
|
||||
// @Router /api/v1/faces/{id} [put]
|
||||
func UpdateFace(router *gin.RouterGroup) {
|
||||
router.PUT("/faces/:id", func(c *gin.Context) {
|
||||
s := Auth(c, acl.ResourcePeople, acl.ActionUpdate)
|
||||
|
||||
@@ -14,7 +14,18 @@ import (
|
||||
|
||||
// SearchFaces finds and returns faces as JSON.
|
||||
//
|
||||
// GET /api/v1/faces
|
||||
// @Summary finds and returns faces as JSON
|
||||
// @Id SearchFaces
|
||||
// @Tags Faces
|
||||
// @Produce json
|
||||
// @Success 200 {object} search.FaceResults
|
||||
// @Failure 400,401,403,429,404 {object} i18n.Response
|
||||
// @Param count query int true "maximum number of results" minimum(1) maximum(100000)
|
||||
// @Param offset query int false "search result offset" minimum(0) maximum(100000)
|
||||
// @Param order query string false "sort order" Enums(subject, added, samples)
|
||||
// @Param hidden query string false "show hidden" Enums(yes, no)
|
||||
// @Param unknown query string false "show unknown" Enums(yes, no)
|
||||
// @Router /api/v1/faces [get]
|
||||
func SearchFaces(router *gin.RouterGroup) {
|
||||
router.GET("/faces", func(c *gin.Context) {
|
||||
s := Auth(c, acl.ResourcePeople, acl.ActionSearch)
|
||||
|
||||
@@ -1335,6 +1335,339 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/errors": {
|
||||
"get": {
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Errors"
|
||||
],
|
||||
"summary": "searches the error logs and returns the results as JSON",
|
||||
"operationId": "GetErrors",
|
||||
"parameters": [
|
||||
{
|
||||
"maximum": 100000,
|
||||
"minimum": 1,
|
||||
"type": "integer",
|
||||
"description": "maximum number of results",
|
||||
"name": "count",
|
||||
"in": "query",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"maximum": 100000,
|
||||
"minimum": 0,
|
||||
"type": "integer",
|
||||
"description": "search result offset",
|
||||
"name": "offset",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"type": "string",
|
||||
"description": "search query",
|
||||
"name": "q",
|
||||
"in": "query"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/entity.Error"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Unauthorized",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Forbidden",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"429": {
|
||||
"description": "Too Many Requests",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"delete": {
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Errors"
|
||||
],
|
||||
"summary": "removes all entries from the error logs",
|
||||
"operationId": "Delete Errors",
|
||||
"responses": {
|
||||
"401": {
|
||||
"description": "Unauthorized",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Forbidden",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"429": {
|
||||
"description": "Too Many Requests",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/faces": {
|
||||
"get": {
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Faces"
|
||||
],
|
||||
"summary": "finds and returns faces as JSON",
|
||||
"operationId": "SearchFaces",
|
||||
"parameters": [
|
||||
{
|
||||
"maximum": 100000,
|
||||
"minimum": 1,
|
||||
"type": "integer",
|
||||
"description": "maximum number of results",
|
||||
"name": "count",
|
||||
"in": "query",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"maximum": 100000,
|
||||
"minimum": 0,
|
||||
"type": "integer",
|
||||
"description": "search result offset",
|
||||
"name": "offset",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"enum": [
|
||||
"subject",
|
||||
"added",
|
||||
"samples"
|
||||
],
|
||||
"type": "string",
|
||||
"description": "sort order",
|
||||
"name": "order",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"enum": [
|
||||
"yes",
|
||||
"no"
|
||||
],
|
||||
"type": "string",
|
||||
"description": "show hidden",
|
||||
"name": "hidden",
|
||||
"in": "query"
|
||||
},
|
||||
{
|
||||
"enum": [
|
||||
"yes",
|
||||
"no"
|
||||
],
|
||||
"type": "string",
|
||||
"description": "show unknown",
|
||||
"name": "unknown",
|
||||
"in": "query"
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/search.Face"
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Unauthorized",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Forbidden",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"429": {
|
||||
"description": "Too Many Requests",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/faces/{id}": {
|
||||
"get": {
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Faces"
|
||||
],
|
||||
"summary": "returns a face as JSON",
|
||||
"operationId": "GetFace",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "face id",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/entity.Face"
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Unauthorized",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Forbidden",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"429": {
|
||||
"description": "Too Many Requests",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"put": {
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"Faces"
|
||||
],
|
||||
"summary": "updates face properties",
|
||||
"operationId": "UpdateFace",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "string",
|
||||
"description": "face id",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"description": "properties to be updated",
|
||||
"name": "face",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/form.Face"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/entity.Face"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"401": {
|
||||
"description": "Unauthorized",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"403": {
|
||||
"description": "Forbidden",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"429": {
|
||||
"description": "Too Many Requests",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/i18n.Response"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/import/{path}": {
|
||||
"post": {
|
||||
"tags": [
|
||||
@@ -1934,6 +2267,17 @@
|
||||
],
|
||||
"summary": "saves the user app settings",
|
||||
"operationId": "SaveSettings",
|
||||
"parameters": [
|
||||
{
|
||||
"description": "user settings",
|
||||
"name": "settings",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/customize.Settings"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
@@ -3392,6 +3736,64 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"entity.Error": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"ID": {
|
||||
"type": "integer"
|
||||
},
|
||||
"Level": {
|
||||
"type": "string"
|
||||
},
|
||||
"Message": {
|
||||
"type": "string"
|
||||
},
|
||||
"Time": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"entity.Face": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"CollisionRadius": {
|
||||
"type": "number"
|
||||
},
|
||||
"Collisions": {
|
||||
"type": "integer"
|
||||
},
|
||||
"CreatedAt": {
|
||||
"type": "string"
|
||||
},
|
||||
"Hidden": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"ID": {
|
||||
"type": "string"
|
||||
},
|
||||
"Kind": {
|
||||
"type": "integer"
|
||||
},
|
||||
"MatchedAt": {
|
||||
"type": "string"
|
||||
},
|
||||
"SampleRadius": {
|
||||
"type": "number"
|
||||
},
|
||||
"Samples": {
|
||||
"type": "integer"
|
||||
},
|
||||
"Src": {
|
||||
"type": "string"
|
||||
},
|
||||
"SubjUID": {
|
||||
"type": "string"
|
||||
},
|
||||
"UpdatedAt": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"entity.File": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4023,6 +4425,17 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"form.Face": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"Hidden": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"SubjUID": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"form.Label": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4301,6 +4714,74 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"search.Face": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"CollisionRadius": {
|
||||
"type": "number"
|
||||
},
|
||||
"Collisions": {
|
||||
"type": "integer"
|
||||
},
|
||||
"CreatedAt": {
|
||||
"type": "string"
|
||||
},
|
||||
"FaceDist": {
|
||||
"type": "number"
|
||||
},
|
||||
"FileUID": {
|
||||
"type": "string"
|
||||
},
|
||||
"Hidden": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"ID": {
|
||||
"type": "string"
|
||||
},
|
||||
"Invalid": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"MarkerUID": {
|
||||
"type": "string"
|
||||
},
|
||||
"MatchedAt": {
|
||||
"type": "string"
|
||||
},
|
||||
"Name": {
|
||||
"type": "string"
|
||||
},
|
||||
"Review": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"SampleRadius": {
|
||||
"type": "number"
|
||||
},
|
||||
"Samples": {
|
||||
"type": "integer"
|
||||
},
|
||||
"Score": {
|
||||
"type": "integer"
|
||||
},
|
||||
"Size": {
|
||||
"type": "integer"
|
||||
},
|
||||
"Src": {
|
||||
"type": "string"
|
||||
},
|
||||
"SubjSrc": {
|
||||
"type": "string"
|
||||
},
|
||||
"SubjUID": {
|
||||
"type": "string"
|
||||
},
|
||||
"Thumb": {
|
||||
"type": "string"
|
||||
},
|
||||
"UpdatedAt": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"search.Photo": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -4528,20 +5009,7 @@
|
||||
1000000,
|
||||
1000000000,
|
||||
60000000000,
|
||||
3600000000000,
|
||||
-9223372036854775808,
|
||||
9223372036854775807,
|
||||
1,
|
||||
1000,
|
||||
1000000,
|
||||
1000000000,
|
||||
60000000000,
|
||||
3600000000000,
|
||||
1,
|
||||
1000,
|
||||
1000000,
|
||||
1000000000,
|
||||
60000000000
|
||||
3600000000000
|
||||
],
|
||||
"x-enum-varnames": [
|
||||
"minDuration",
|
||||
@@ -4559,20 +5027,7 @@
|
||||
"Millisecond",
|
||||
"Second",
|
||||
"Minute",
|
||||
"Hour",
|
||||
"minDuration",
|
||||
"maxDuration",
|
||||
"Nanosecond",
|
||||
"Microsecond",
|
||||
"Millisecond",
|
||||
"Second",
|
||||
"Minute",
|
||||
"Hour",
|
||||
"Nanosecond",
|
||||
"Microsecond",
|
||||
"Millisecond",
|
||||
"Second",
|
||||
"Minute"
|
||||
"Hour"
|
||||
]
|
||||
}
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user