API: Add and update Swagger annotations #2132

Signed-off-by: Michael Mayer <michael@photoprism.app>

internal/api/albums.go

@@ -135,8 +135,7 @@ func CreateAlbum(router *gin.RouterGroup) {
 // UpdateAlbum updates album metadata like title and description.
 //
 //	@Tags	Albums
-//
-//	@Route	/api/v1/albums/{uid} [put]
+//	@Router	/api/v1/albums/{uid} [put]
 func UpdateAlbum(router *gin.RouterGroup) {
 	router.PUT("/albums/:uid", func(c *gin.Context) {
 		s := Auth(c, acl.ResourceAlbums, acl.ActionUpdate)
@@ -202,8 +201,7 @@ func UpdateAlbum(router *gin.RouterGroup) {
 // DeleteAlbum deletes an existing album.
 //
 //	@Tags	Albums
-//
-//	@Route	/api/v1/albums/{uid} [delete]
+//	@Router	/api/v1/albums/{uid} [delete]
 func DeleteAlbum(router *gin.RouterGroup) {
 	router.DELETE("/albums/:uid", func(c *gin.Context) {
 		s := Auth(c, acl.ResourceAlbums, acl.ActionDelete)
@@ -325,8 +323,7 @@ func LikeAlbum(router *gin.RouterGroup) {
 //   - uid: string Album UID
 //
 //	@Tags	Albums
-//
-//	@Route	/api/v1/albums/{uid}/like [delete]
+//	@Router	/api/v1/albums/{uid}/like [delete]
 func DislikeAlbum(router *gin.RouterGroup) {
 	router.DELETE("/albums/:uid/like", func(c *gin.Context) {
 		s := Auth(c, acl.ResourceAlbums, acl.ActionUpdate)
@@ -544,7 +541,7 @@ func AddPhotosToAlbum(router *gin.RouterGroup) {
 // RemovePhotosFromAlbum removes photos from an album.
 //
 //	@Tags	Albums
-//	@Route	/api/v1/albums/{uid}/photos [delete]
+//	@Router	/api/v1/albums/{uid}/photos [delete]
 func RemovePhotosFromAlbum(router *gin.RouterGroup) {
 	router.DELETE("/albums/:uid/photos", func(c *gin.Context) {
 		s := Auth(c, acl.ResourceAlbums, acl.ActionUpdate)

internal/api/thumbnails.go

@@ -18,13 +18,14 @@ import (
 
 // GetThumb returns a thumbnail image matching the file hash, crop area, and type.
 //
-//	@Summary	"returns a thumbnail image matching the file hash, crop area, and type"
-//	@Produce	"image/jpeg"
-//	@Tags		Thumbnails
-//	@Param		thumb	path	string	true	"SHA1 file hash plus optional crop area"
-//	@Param		token	path	string	true	"user-specific security token provided with session"
-//	@Param		size	path	string	true	"thumbnail size"
-//	@Route		/api/v1/t/{thumb}/{token}/{size} [get]
+//	@Summary	returns a thumbnail image with the requested size
+//	@Id			GetThumb
+//	@Produce	image/jpeg
+//	@Tags		Images, Files
+//	@Param		thumb path string true "SHA1 file hash, optionally with a crop area suffixed, e.g. '-016014058037'"
+//	@Param		token path string true "user-specific security token provided with session"
+//	@Param		size path string true "thumbnail size"
+//	@Router		/api/v1/t/{hash}/{token}/{size} [get]
 func GetThumb(router *gin.RouterGroup) {
 	router.GET("/t/:thumb/:token/:size", func(c *gin.Context) {
 		if InvalidPreviewToken(c) {

internal/api/users_password.go

@@ -19,7 +19,7 @@ import (
 // UpdateUserPassword changes the password of the currently authenticated user.
 //
 //	@Tags	Users, Authentication
-//	@Route /api/v1/users/{uid}/password [put]
+//	@Router /api/v1/users/{uid}/password [put]
 func UpdateUserPassword(router *gin.RouterGroup) {
 	router.PUT("/users/:uid/password", func(c *gin.Context) {
 		conf := get.Config()

internal/api/users_sessions.go

@@ -19,7 +19,7 @@ import (
 // FindUserSessions finds user sessions and returns them as JSON.
 //
 //	@Tags	Users, Authentication
-//	@Route /api/v1/users/{uid}/sessions [get]
+//	@Router /api/v1/users/{uid}/sessions [get]
 func FindUserSessions(router *gin.RouterGroup) {
 	router.GET("/users/:uid/sessions", func(c *gin.Context) {
 		// Check if the session user is has user management privileges.

internal/api/users_update.go

@@ -17,7 +17,7 @@ import (
 // UpdateUser updates the profile information of the currently authenticated user.
 //
 //	@Tags	Users
-//	@Route /api/v1/users/{uid} [put]
+//	@Router /api/v1/users/{uid} [put]
 func UpdateUser(router *gin.RouterGroup) {
 	router.PUT("/users/:uid", func(c *gin.Context) {
 		conf := get.Config()

internal/api/users_upload.go

@@ -25,7 +25,7 @@ import (
 // UploadUserFiles adds files to the user upload folder, from where they can be moved and indexed.
 //
 //	@Tags	Users, Files
-//	@Route /users/{uid}/upload/{token} [post]
+//	@Router /users/{uid}/upload/{token} [post]
 func UploadUserFiles(router *gin.RouterGroup) {
 	router.POST("/users/:uid/upload/:token", func(c *gin.Context) {
 		conf := get.Config()

internal/api/video.go

@@ -17,14 +17,16 @@ import (
 	"github.com/photoprism/photoprism/pkg/media/video"
 )
 
-// GetVideo streams video content.
+// GetVideo returns a video, optionally limited to a byte range for streaming.
 //
-// The request parameters are:
-//
-//   - hash: string The photo or video file hash as returned by the search API
-//   - type: string Video format
-//
-// GET /api/v1/videos/:hash/:token/:type
+//	@Summary	returns a video, optionally limited to a byte range for streaming
+//	@Id			GetVideo
+//	@Produce	video/mp4
+//	@Tags		Files, Videos
+//	@Param		thumb path string true "SHA1 video file hash"
+//	@Param		token path string true "user-specific security token provided with session"
+//	@Param		format path string true "video format, e.g. mp4"
+//	@Router		/api/v1/videos/{hash}/{token}/{format} [get]
 func GetVideo(router *gin.RouterGroup) {
 	router.GET("/videos/:hash/:token/:format", func(c *gin.Context) {
 		if InvalidPreviewToken(c) {