Improved REST route docs, see #12

Hard to test locally as godoc -http ":80" doesn't seem to work outside the GOPATH
photoprism · Nov 6, 2018 · e66e9e4 · e66e9e4
1 parent 5868d4e
commit e66e9e4
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 9 deletions.
diff --git a/internal/api/photos.go b/internal/api/photos.go
@@ -11,8 +11,20 @@ import (
 	"github.com/photoprism/photoprism/internal/photoprism"
 )
 
-// GET /api/v1/photos
-// Parameters see https://github.com/photoprism/photoprism/blob/develop/internal/forms/photo-search.go
+// `GET /api/v1/photos`
+//
+// Query:
+//   - `q`: string Query string            `form:""`
+//	 - `tags`: string Tags          string    `form:"tags"`
+//	 - `cat`: string Category
+//	 - `country`: string Country code
+//	 - `camera`: int Camera ID
+//	 - `order`: string Sort order
+//	 - `count`: int Max result count (required)
+//	 - `offset`: int Result offset
+//	 - `before`: date Find photos taken before (format: "2006-01-02")
+//	 - `after`: date Find photos taken after (format: "2006-01-02")
+//	 - `favorites`: bool Find favorites only
 func GetPhotos(router *gin.RouterGroup, conf *photoprism.Config) {
 	router.GET("/photos", func(c *gin.Context) {
 		var form forms.PhotoSearchForm
@@ -34,7 +46,10 @@ func GetPhotos(router *gin.RouterGroup, conf *photoprism.Config) {
 	})
 }
 
-// POST /api/v1/photos/:photoId/like
+// `POST /api/v1/photos/:photoId/like`
+//
+// Parameters:
+//   - `photoId`: Photo ID as returned by the API
 func LikePhoto(router *gin.RouterGroup, conf *photoprism.Config) {
 	router.POST("/photos/:photoId/like", func(c *gin.Context) {
 		search := photoprism.NewSearch(conf.OriginalsPath, conf.GetDb())
@@ -53,7 +68,10 @@ func LikePhoto(router *gin.RouterGroup, conf *photoprism.Config) {
 	})
 }
 
-// DELETE /api/v1/photos/:photoId/like
+// `DELETE /api/v1/photos/:photoId/like`
+//
+// Parameters:
+//   - `photoId`: Photo ID as returned by the API
 func DislikePhoto(router *gin.RouterGroup, conf *photoprism.Config) {
 	router.DELETE("/photos/:photoId/like", func(c *gin.Context) {
 		search := photoprism.NewSearch(conf.OriginalsPath, conf.GetDb())

diff --git a/internal/api/thumbnails.go b/internal/api/thumbnails.go
@@ -15,10 +15,12 @@ var photoIconSvg = []byte(`
 <path d="M21 19V5c0-1.1-.9-2-2-2H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2zM8.5 13.5l2.5 3.01L14.5 12l4.5 6H5l3.5-4.5z"/>
 </svg>`)
 
-// GET /api/v1/thumbnails/:type/:size/:hash
-// :type string Format, either "fit" or "square"
-// :size int Size in pixels
-// :hash string The file hash as returned by the search API
+// `GET /api/v1/thumbnails/:type/:size/:hash`
+//
+// Parameters:
+//   - `type`: string Format, either "fit" or "square"
+//   - `size`: int Size in pixels
+//   - `hash`: string The file hash as returned by the search API
 func GetThumbnail(router *gin.RouterGroup, conf *photoprism.Config) {
 	router.GET("/thumbnails/:type/:size/:hash", func(c *gin.Context) {
 		fileHash := c.Param("hash")

diff --git a/internal/forms/photo-search.go b/internal/forms/photo-search.go
@@ -15,5 +15,5 @@ type PhotoSearchForm struct {
 	Offset        int       `form:"offset"`
 	Before        time.Time `form:"before" time_format:"2006-01-02"`
 	After         time.Time `form:"after" time_format:"2006-01-02"`
-	FavoritesOnly bool      `form:"category"`
+	FavoritesOnly bool      `form:"favorites"`
 }