feat: add SwaggerUI and v1 API docs (#2115)

* - Refactor several API routes from anonymous functions to regular definitions. Required to add parseable documentation comments.

- Add API documentation comments using Swag Declarative Comments Format

- Add echo-swagger to serve Swagger-UI at /api/index.html

- Fix error response from extraneous parameter resourceId to relatedMemoId in DELETE("/memo/:memoId/relation/:relatedMemoId/type/:relationType")

- Add an auto-generated ./docs/api/v1.md for quick reference on repo (generated by swagger-markdown)

- Add auxiliary scripts to generate docs.go and swagger.yaml

* fix: golangci-lint errors

* fix: go fmt flag in swag scripts

api/v1/http_getter.go

@@ -11,43 +11,67 @@ import (
 
 func (*APIV1Service) registerGetterPublicRoutes(g *echo.Group) {
 	// GET /get/httpmeta?url={url} - Get website meta.
-	g.GET("/get/httpmeta", func(c echo.Context) error {
-		urlStr := c.QueryParam("url")
-		if urlStr == "" {
-			return echo.NewHTTPError(http.StatusBadRequest, "Missing website url")
-		}
-		if _, err := url.Parse(urlStr); err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, "Wrong url").SetInternal(err)
-		}
-
-		htmlMeta, err := getter.GetHTMLMeta(urlStr)
-		if err != nil {
-			return echo.NewHTTPError(http.StatusNotAcceptable, fmt.Sprintf("Failed to get website meta with url: %s", urlStr)).SetInternal(err)
-		}
-		return c.JSON(http.StatusOK, htmlMeta)
-	})
+	g.GET("/get/httpmeta", httpmeta)
 
 	// GET /get/image?url={url} - Get image.
-	g.GET("/get/image", func(c echo.Context) error {
-		urlStr := c.QueryParam("url")
-		if urlStr == "" {
-			return echo.NewHTTPError(http.StatusBadRequest, "Missing image url")
-		}
-		if _, err := url.Parse(urlStr); err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, "Wrong url").SetInternal(err)
-		}
-
-		image, err := getter.GetImage(urlStr)
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Failed to get image url: %s", urlStr)).SetInternal(err)
-		}
-
-		c.Response().Writer.WriteHeader(http.StatusOK)
-		c.Response().Writer.Header().Set("Content-Type", image.Mediatype)
-		c.Response().Writer.Header().Set(echo.HeaderCacheControl, "max-age=31536000, immutable")
-		if _, err := c.Response().Writer.Write(image.Blob); err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to write image blob").SetInternal(err)
-		}
-		return nil
-	})
+	g.GET("/get/image", image)
+}
+
+// httpmeta godoc
+//
+//	@Summary	Get website metadata
+//	@Tags		get
+//	@Produce	json
+//	@Param		url	query		string			true	"Website URL"
+//	@Success	200	{object}	getter.HTMLMeta	"Extracted metadata"
+//	@Failure	400	{object}	nil				"Missing website url | Wrong url"
+//	@Failure	406	{object}	nil				"Failed to get website meta with url: %s"
+//	@Router		/o/get/httpmeta [GET]
+func httpmeta(c echo.Context) error {
+	urlStr := c.QueryParam("url")
+	if urlStr == "" {
+		return echo.NewHTTPError(http.StatusBadRequest, "Missing website url")
+	}
+	if _, err := url.Parse(urlStr); err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "Wrong url").SetInternal(err)
+	}
+
+	htmlMeta, err := getter.GetHTMLMeta(urlStr)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusNotAcceptable, fmt.Sprintf("Failed to get website meta with url: %s", urlStr)).SetInternal(err)
+	}
+	return c.JSON(http.StatusOK, htmlMeta)
+}
+
+// image godoc
+//
+//	@Summary	Get image from URL
+//	@Tags		get
+//	@Produce	image/*
+//	@Param		url	query		string	true	"Image url"
+//	@Success	200	{object}	nil		"Image"
+//	@Failure	400	{object}	nil		"Missing image url | Wrong url | Failed to get image url: %s"
+//	@Failure	500	{object}	nil		"Failed to write image blob"
+//	@Router		/o/get/image [GET]
+func image(c echo.Context) error {
+	urlStr := c.QueryParam("url")
+	if urlStr == "" {
+		return echo.NewHTTPError(http.StatusBadRequest, "Missing image url")
+	}
+	if _, err := url.Parse(urlStr); err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "Wrong url").SetInternal(err)
+	}
+
+	image, err := getter.GetImage(urlStr)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Failed to get image url: %s", urlStr)).SetInternal(err)
+	}
+
+	c.Response().Writer.WriteHeader(http.StatusOK)
+	c.Response().Writer.Header().Set("Content-Type", image.Mediatype)
+	c.Response().Writer.Header().Set(echo.HeaderCacheControl, "max-age=31536000, immutable")
+	if _, err := c.Response().Writer.Write(image.Blob); err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to write image blob").SetInternal(err)
+	}
+	return nil
 }

api/v1/memo_organizer.go

@@ -22,60 +22,77 @@ type UpsertMemoOrganizerRequest struct {
 }
 
 func (s *APIV1Service) registerMemoOrganizerRoutes(g *echo.Group) {
-	g.POST("/memo/:memoId/organizer", func(c echo.Context) error {
-		ctx := c.Request().Context()
-		memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
-		}
+	g.POST("/memo/:memoId/organizer", s.organizeMemo)
+}
 
-		userID, ok := c.Get(auth.UserIDContextKey).(int32)
-		if !ok {
-			return echo.NewHTTPError(http.StatusUnauthorized, "Missing user in session")
-		}
+// organizeMemo godoc
+//
+//	@Summary	Organize memo (pin/unpin)
+//	@Tags		memo-organizer
+//	@Accept		json
+//	@Produce	json
+//	@Param		memoId	path		int							true	"ID of memo to organize"
+//	@Param		body	body		UpsertMemoOrganizerRequest	true	"Memo organizer object"
+//	@Success	200		{object}	store.Memo					"Memo information"
+//	@Failure	400		{object}	nil							"ID is not a number: %s | Malformatted post memo organizer request"
+//	@Failure	401		{object}	nil							"Missing user in session | Unauthorized"
+//	@Failure	404		{object}	nil							"Memo not found: %v"
+//	@Failure	500		{object}	nil							"Failed to find memo | Failed to upsert memo organizer | Failed to find memo by ID: %v | Failed to compose memo response"
+//	@Security	ApiKeyAuth
+//	@Router		/api/v1/memo/{memoId}/organizer [POST]
+func (s *APIV1Service) organizeMemo(c echo.Context) error {
+	ctx := c.Request().Context()
+	memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
+	}
 
-		memo, err := s.Store.GetMemo(ctx, &store.FindMemo{
-			ID: &memoID,
-		})
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find memo").SetInternal(err)
-		}
-		if memo == nil {
-			return echo.NewHTTPError(http.StatusNotFound, fmt.Sprintf("Memo not found: %v", memoID))
-		}
-		if memo.CreatorID != userID {
-			return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
-		}
+	userID, ok := c.Get(auth.UserIDContextKey).(int32)
+	if !ok {
+		return echo.NewHTTPError(http.StatusUnauthorized, "Missing user in session")
+	}
 
-		request := &UpsertMemoOrganizerRequest{}
-		if err := json.NewDecoder(c.Request().Body).Decode(request); err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post memo organizer request").SetInternal(err)
-		}
+	memo, err := s.Store.GetMemo(ctx, &store.FindMemo{
+		ID: &memoID,
+	})
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find memo").SetInternal(err)
+	}
+	if memo == nil {
+		return echo.NewHTTPError(http.StatusNotFound, fmt.Sprintf("Memo not found: %v", memoID))
+	}
+	if memo.CreatorID != userID {
+		return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
+	}
 
-		upsert := &store.MemoOrganizer{
-			MemoID: memoID,
-			UserID: userID,
-			Pinned: request.Pinned,
-		}
-		_, err = s.Store.UpsertMemoOrganizer(ctx, upsert)
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to upsert memo organizer").SetInternal(err)
-		}
+	request := &UpsertMemoOrganizerRequest{}
+	if err := json.NewDecoder(c.Request().Body).Decode(request); err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post memo organizer request").SetInternal(err)
+	}
 
-		memo, err = s.Store.GetMemo(ctx, &store.FindMemo{
-			ID: &memoID,
-		})
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, fmt.Sprintf("Failed to find memo by ID: %v", memoID)).SetInternal(err)
-		}
-		if memo == nil {
-			return echo.NewHTTPError(http.StatusNotFound, fmt.Sprintf("Memo not found: %v", memoID))
-		}
+	upsert := &store.MemoOrganizer{
+		MemoID: memoID,
+		UserID: userID,
+		Pinned: request.Pinned,
+	}
+	_, err = s.Store.UpsertMemoOrganizer(ctx, upsert)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to upsert memo organizer").SetInternal(err)
+	}
 
-		memoResponse, err := s.convertMemoFromStore(ctx, memo)
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to compose memo response").SetInternal(err)
-		}
-		return c.JSON(http.StatusOK, memoResponse)
+	memo, err = s.Store.GetMemo(ctx, &store.FindMemo{
+		ID: &memoID,
 	})
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, fmt.Sprintf("Failed to find memo by ID: %v", memoID)).SetInternal(err)
+	}
+	if memo == nil {
+		return echo.NewHTTPError(http.StatusNotFound, fmt.Sprintf("Memo not found: %v", memoID))
+	}
+
+	memoResponse, err := s.convertMemoFromStore(ctx, memo)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to compose memo response").SetInternal(err)
+	}
+	return c.JSON(http.StatusOK, memoResponse)
 }

api/v1/memo_relation.go

@@ -29,66 +29,117 @@ type UpsertMemoRelationRequest struct {
 }
 
 func (s *APIV1Service) registerMemoRelationRoutes(g *echo.Group) {
-	g.POST("/memo/:memoId/relation", func(c echo.Context) error {
-		ctx := c.Request().Context()
-		memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
-		}
+	g.GET("/memo/:memoId/relation", s.getMemoRelationList)
+	g.POST("/memo/:memoId/relation", s.createMemoRelation)
+	g.DELETE("/memo/:memoId/relation/:relatedMemoId/type/:relationType", s.deleteMemoRelation)
+}
 
-		request := &UpsertMemoRelationRequest{}
-		if err := json.NewDecoder(c.Request().Body).Decode(request); err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post memo relation request").SetInternal(err)
-		}
+// getMemoRelationList godoc
+//
+//	@Summary	Get a list of Memo Relations
+//	@Tags		memo-relation
+//	@Accept		json
+//	@Produce	json
+//	@Param		memoId	path		int						true	"ID of memo to find relations"
+//	@Success	200		{object}	[]store.MemoRelation	"Memo relation information list"
+//	@Failure	400		{object}	nil						"ID is not a number: %s"
+//	@Failure	500		{object}	nil						"Failed to list memo relations"
+//	@Router		/api/v1/memo/{memoId}/relation [GET]
+func (s *APIV1Service) getMemoRelationList(c echo.Context) error {
+	ctx := c.Request().Context()
+	memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
+	}
 
-		memoRelation, err := s.Store.UpsertMemoRelation(ctx, &store.MemoRelation{
-			MemoID:        memoID,
-			RelatedMemoID: request.RelatedMemoID,
-			Type:          store.MemoRelationType(request.Type),
-		})
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to upsert memo relation").SetInternal(err)
-		}
-		return c.JSON(http.StatusOK, memoRelation)
+	memoRelationList, err := s.Store.ListMemoRelations(ctx, &store.FindMemoRelation{
+		MemoID: &memoID,
 	})
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to list memo relations").SetInternal(err)
+	}
+	return c.JSON(http.StatusOK, memoRelationList)
+}
 
-	g.GET("/memo/:memoId/relation", func(c echo.Context) error {
-		ctx := c.Request().Context()
-		memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
-		}
+// createMemoRelation godoc
+//
+//	@Summary		Create Memo Relation
+//	@Description	Create a relation between two memos
+//	@Tags			memo-relation
+//	@Accept			json
+//	@Produce		json
+//	@Param			memoId	path		int							true	"ID of memo to relate"
+//	@Param			body	body		UpsertMemoRelationRequest	true	"Memo relation object"
+//	@Success		200		{object}	store.MemoRelation			"Memo relation information"
+//	@Failure		400		{object}	nil							"ID is not a number: %s | Malformatted post memo relation request"
+//	@Failure		500		{object}	nil							"Failed to upsert memo relation"
+//	@Router			/api/v1/memo/{memoId}/relation [POST]
+//
+// NOTES:
+// - Currently not secured
+// - It's possible to create relations to memos that doesn't exist, which will trigger 404 errors when the frontend tries to load them.
+// - It's possible to create multiple relations, though the interface only shows first.
+func (s *APIV1Service) createMemoRelation(c echo.Context) error {
+	ctx := c.Request().Context()
+	memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
+	}
+
+	request := &UpsertMemoRelationRequest{}
+	if err := json.NewDecoder(c.Request().Body).Decode(request); err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post memo relation request").SetInternal(err)
+	}
 
-		memoRelationList, err := s.Store.ListMemoRelations(ctx, &store.FindMemoRelation{
-			MemoID: &memoID,
-		})
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to list memo relations").SetInternal(err)
-		}
-		return c.JSON(http.StatusOK, memoRelationList)
+	memoRelation, err := s.Store.UpsertMemoRelation(ctx, &store.MemoRelation{
+		MemoID:        memoID,
+		RelatedMemoID: request.RelatedMemoID,
+		Type:          store.MemoRelationType(request.Type),
 	})
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to upsert memo relation").SetInternal(err)
+	}
+	return c.JSON(http.StatusOK, memoRelation)
+}
 
-	g.DELETE("/memo/:memoId/relation/:relatedMemoId/type/:relationType", func(c echo.Context) error {
-		ctx := c.Request().Context()
-		memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Memo ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
-		}
-		relatedMemoID, err := util.ConvertStringToInt32(c.Param("relatedMemoId"))
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Related memo ID is not a number: %s", c.Param("resourceId"))).SetInternal(err)
-		}
-		relationType := store.MemoRelationType(c.Param("relationType"))
+// deleteMemoRelation godoc
+//
+//	@Summary		Delete a Memo Relation
+//	@Description	Removes a relation between two memos
+//	@Tags			memo-relation
+//	@Accept			json
+//	@Produce		json
+//	@Param			memoId			path		int					true	"ID of memo to find relations"
+//	@Param			relatedMemoId	path		int					true	"ID of memo to remove relation to"
+//	@Param			relationType	path		MemoRelationType	true	"Type of relation to remove"
+//	@Success		200				{boolean}	true				"Memo relation deleted"
+//	@Failure		400				{object}	nil					"Memo ID is not a number: %s | Related memo ID is not a number: %s"
+//	@Failure		500				{object}	nil					"Failed to delete memo relation"
+//	@Router			/api/v1/memo/{memoId}/relation/{relatedMemoId}/type/{relationType} [DELETE]
+//
+// NOTES:
+// - Currently not secured.
+// - Will always return true, even if the relation doesn't exist.
+func (s *APIV1Service) deleteMemoRelation(c echo.Context) error {
+	ctx := c.Request().Context()
+	memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Memo ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
+	}
+	relatedMemoID, err := util.ConvertStringToInt32(c.Param("relatedMemoId"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Related memo ID is not a number: %s", c.Param("relatedMemoId"))).SetInternal(err)
+	}
+	relationType := store.MemoRelationType(c.Param("relationType"))
 
-		if err := s.Store.DeleteMemoRelation(ctx, &store.DeleteMemoRelation{
-			MemoID:        &memoID,
-			RelatedMemoID: &relatedMemoID,
-			Type:          &relationType,
-		}); err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to delete memo relation").SetInternal(err)
-		}
-		return c.JSON(http.StatusOK, true)
-	})
+	if err := s.Store.DeleteMemoRelation(ctx, &store.DeleteMemoRelation{
+		MemoID:        &memoID,
+		RelatedMemoID: &relatedMemoID,
+		Type:          &relationType,
+	}); err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to delete memo relation").SetInternal(err)
+	}
+	return c.JSON(http.StatusOK, true)
 }
 
 func convertMemoRelationFromStore(memoRelation *store.MemoRelation) *MemoRelation {

api/v1/memo_resource.go

@@ -35,101 +35,147 @@ type MemoResourceDelete struct {
 }
 
 func (s *APIV1Service) registerMemoResourceRoutes(g *echo.Group) {
-	g.POST("/memo/:memoId/resource", func(c echo.Context) error {
-		ctx := c.Request().Context()
-		memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
-		}
+	g.GET("/memo/:memoId/resource", s.getMemoResourceList)
+	g.POST("/memo/:memoId/resource", s.bindMemoResource)
+	g.DELETE("/memo/:memoId/resource/:resourceId", s.unbindMemoResource)
+}
 
-		userID, ok := c.Get(auth.UserIDContextKey).(int32)
-		if !ok {
-			return echo.NewHTTPError(http.StatusUnauthorized, "Missing user in session")
-		}
-		request := &UpsertMemoResourceRequest{}
-		if err := json.NewDecoder(c.Request().Body).Decode(request); err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post memo resource request").SetInternal(err)
-		}
-		resource, err := s.Store.GetResource(ctx, &store.FindResource{
-			ID: &request.ResourceID,
-		})
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to fetch resource").SetInternal(err)
-		}
-		if resource == nil {
-			return echo.NewHTTPError(http.StatusBadRequest, "Resource not found").SetInternal(err)
-		} else if resource.CreatorID != userID {
-			return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized to bind this resource").SetInternal(err)
-		}
+// getMemoResourceList godoc
+//
+//	@Summary	Get resource list of a memo
+//	@Tags		memo-resource
+//	@Accept		json
+//	@Produce	json
+//	@Param		memoId	path		int			true	"ID of memo to fetch resource list from"
+//	@Success	200		{object}	[]Resource	"Memo resource list"
+//	@Failure	400		{object}	nil			"ID is not a number: %s"
+//	@Failure	500		{object}	nil			"Failed to fetch resource list"
+//	@Router		/api/v1/memo/{memoId}/resource [GET]
+func (s *APIV1Service) getMemoResourceList(c echo.Context) error {
+	ctx := c.Request().Context()
+	memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
+	}
 
-		upsert := &store.UpsertMemoResource{
-			MemoID:     memoID,
-			ResourceID: request.ResourceID,
-			CreatedTs:  time.Now().Unix(),
-		}
-		if request.UpdatedTs != nil {
-			upsert.UpdatedTs = request.UpdatedTs
-		}
-		if _, err := s.Store.UpsertMemoResource(ctx, upsert); err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to upsert memo resource").SetInternal(err)
-		}
-		return c.JSON(http.StatusOK, true)
+	list, err := s.Store.ListResources(ctx, &store.FindResource{
+		MemoID: &memoID,
 	})
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to fetch resource list").SetInternal(err)
+	}
+	resourceList := []*Resource{}
+	for _, resource := range list {
+		resourceList = append(resourceList, convertResourceFromStore(resource))
+	}
+	return c.JSON(http.StatusOK, resourceList)
+}
 
-	g.GET("/memo/:memoId/resource", func(c echo.Context) error {
-		ctx := c.Request().Context()
-		memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
-		}
+// bindMemoResource godoc
+//
+//	@Summary	Bind resource to memo
+//	@Tags		memo-resource
+//	@Accept		json
+//	@Produce	json
+//	@Param		memoId	path		int							true	"ID of memo to bind resource to"
+//	@Param		body	body		UpsertMemoResourceRequest	true	"Memo resource request object"
+//	@Success	200		{boolean}	true						"Memo resource binded"
+//	@Failure	400		{object}	nil							"ID is not a number: %s | Malformatted post memo resource request | Resource not found"
+//	@Failure	401		{object}	nil							"Missing user in session | Unauthorized to bind this resource"
+//	@Failure	500		{object}	nil							"Failed to fetch resource | Failed to upsert memo resource"
+//	@Security	ApiKeyAuth
+//	@Router		/api/v1/memo/{memoId}/resource [POST]
+//
+// NOTES:
+// - Passing 0 to updatedTs will set it to 0 in the database, which is probably unwanted.
+func (s *APIV1Service) bindMemoResource(c echo.Context) error {
+	ctx := c.Request().Context()
+	memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
+	}
 
-		list, err := s.Store.ListResources(ctx, &store.FindResource{
-			MemoID: &memoID,
-		})
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to fetch resource list").SetInternal(err)
-		}
-		resourceList := []*Resource{}
-		for _, resource := range list {
-			resourceList = append(resourceList, convertResourceFromStore(resource))
-		}
-		return c.JSON(http.StatusOK, resourceList)
+	userID, ok := c.Get(auth.UserIDContextKey).(int32)
+	if !ok {
+		return echo.NewHTTPError(http.StatusUnauthorized, "Missing user in session")
+	}
+	request := &UpsertMemoResourceRequest{}
+	if err := json.NewDecoder(c.Request().Body).Decode(request); err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post memo resource request").SetInternal(err)
+	}
+	resource, err := s.Store.GetResource(ctx, &store.FindResource{
+		ID: &request.ResourceID,
 	})
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to fetch resource").SetInternal(err)
+	}
+	if resource == nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "Resource not found").SetInternal(err)
+	} else if resource.CreatorID != userID {
+		return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized to bind this resource").SetInternal(err)
+	}
 
-	g.DELETE("/memo/:memoId/resource/:resourceId", func(c echo.Context) error {
-		ctx := c.Request().Context()
-		userID, ok := c.Get(auth.UserIDContextKey).(int32)
-		if !ok {
-			return echo.NewHTTPError(http.StatusUnauthorized, "Missing user in session")
-		}
-		memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Memo ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
-		}
-		resourceID, err := util.ConvertStringToInt32(c.Param("resourceId"))
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Resource ID is not a number: %s", c.Param("resourceId"))).SetInternal(err)
-		}
+	upsert := &store.UpsertMemoResource{
+		MemoID:     memoID,
+		ResourceID: request.ResourceID,
+		CreatedTs:  time.Now().Unix(),
+	}
+	if request.UpdatedTs != nil {
+		upsert.UpdatedTs = request.UpdatedTs
+	}
+	if _, err := s.Store.UpsertMemoResource(ctx, upsert); err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to upsert memo resource").SetInternal(err)
+	}
+	return c.JSON(http.StatusOK, true)
+}
 
-		memo, err := s.Store.GetMemo(ctx, &store.FindMemo{
-			ID: &memoID,
-		})
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find memo").SetInternal(err)
-		}
-		if memo == nil {
-			return echo.NewHTTPError(http.StatusBadRequest, "Memo not found")
-		}
-		if memo.CreatorID != userID {
-			return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
-		}
+// unbindMemoResource godoc
+//
+//	@Summary	Unbind resource from memo
+//	@Tags		memo-resource
+//	@Accept		json
+//	@Produce	json
+//	@Param		memoId		path		int		true	"ID of memo to unbind resource from"
+//	@Param		resourceId	path		int		true	"ID of resource to unbind from memo"
+//	@Success	200			{boolean}	true	"Memo resource unbinded. *200 is returned even if the reference doesn't exists "
+//	@Failure	400			{object}	nil		"Memo ID is not a number: %s | Resource ID is not a number: %s | Memo not found"
+//	@Failure	401			{object}	nil		"Missing user in session | Unauthorized"
+//	@Failure	500			{object}	nil		"Failed to find memo | Failed to fetch resource list"
+//	@Security	ApiKeyAuth
+//	@Router		/api/v1/memo/{memoId}/resource/{resourceId} [DELETE]
+func (s *APIV1Service) unbindMemoResource(c echo.Context) error {
+	ctx := c.Request().Context()
+	userID, ok := c.Get(auth.UserIDContextKey).(int32)
+	if !ok {
+		return echo.NewHTTPError(http.StatusUnauthorized, "Missing user in session")
+	}
+	memoID, err := util.ConvertStringToInt32(c.Param("memoId"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Memo ID is not a number: %s", c.Param("memoId"))).SetInternal(err)
+	}
+	resourceID, err := util.ConvertStringToInt32(c.Param("resourceId"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Resource ID is not a number: %s", c.Param("resourceId"))).SetInternal(err)
+	}
 
-		if err := s.Store.DeleteMemoResource(ctx, &store.DeleteMemoResource{
-			MemoID:     &memoID,
-			ResourceID: &resourceID,
-		}); err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to fetch resource list").SetInternal(err)
-		}
-		return c.JSON(http.StatusOK, true)
+	memo, err := s.Store.GetMemo(ctx, &store.FindMemo{
+		ID: &memoID,
 	})
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find memo").SetInternal(err)
+	}
+	if memo == nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "Memo not found")
+	}
+	if memo.CreatorID != userID {
+		return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
+	}
+
+	if err := s.Store.DeleteMemoResource(ctx, &store.DeleteMemoResource{
+		MemoID:     &memoID,
+		ResourceID: &resourceID,
+	}); err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to fetch resource list").SetInternal(err)
+	}
+	return c.JSON(http.StatusOK, true)
 }

api/v1/rss.go

@@ -21,63 +21,84 @@ const maxRSSItemCount = 100
 const maxRSSItemTitleLength = 100
 
 func (s *APIV1Service) registerRSSRoutes(g *echo.Group) {
-	g.GET("/explore/rss.xml", func(c echo.Context) error {
-		ctx := c.Request().Context()
-		systemCustomizedProfile, err := s.getSystemCustomizedProfile(ctx)
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to get system customized profile").SetInternal(err)
-		}
+	g.GET("/explore/rss.xml", s.getRSS)
+	g.GET("/u/:id/rss.xml", s.getUserRSS)
+}
 
-		normalStatus := store.Normal
-		memoFind := store.FindMemo{
-			RowStatus:      &normalStatus,
-			VisibilityList: []store.Visibility{store.Public},
-		}
-		memoList, err := s.Store.ListMemos(ctx, &memoFind)
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find memo list").SetInternal(err)
-		}
+// getRSS godoc
+//
+//	@Summary	Get RSS
+//	@Tags		rss
+//	@Produce	xml
+//	@Success	200	{object}	nil	"RSS"
+//	@Failure	500	{object}	nil	"Failed to get system customized profile | Failed to find memo list | Failed to generate rss"
+//	@Router		/explore/rss.xml [GET]
+func (s *APIV1Service) getRSS(c echo.Context) error {
+	ctx := c.Request().Context()
+	systemCustomizedProfile, err := s.getSystemCustomizedProfile(ctx)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to get system customized profile").SetInternal(err)
+	}
 
-		baseURL := c.Scheme() + "://" + c.Request().Host
-		rss, err := s.generateRSSFromMemoList(ctx, memoList, baseURL, systemCustomizedProfile)
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to generate rss").SetInternal(err)
-		}
-		c.Response().Header().Set(echo.HeaderContentType, echo.MIMEApplicationXMLCharsetUTF8)
-		return c.String(http.StatusOK, rss)
-	})
+	normalStatus := store.Normal
+	memoFind := store.FindMemo{
+		RowStatus:      &normalStatus,
+		VisibilityList: []store.Visibility{store.Public},
+	}
+	memoList, err := s.Store.ListMemos(ctx, &memoFind)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find memo list").SetInternal(err)
+	}
 
-	g.GET("/u/:id/rss.xml", func(c echo.Context) error {
-		ctx := c.Request().Context()
-		id, err := util.ConvertStringToInt32(c.Param("id"))
-		if err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, "User id is not a number").SetInternal(err)
-		}
+	baseURL := c.Scheme() + "://" + c.Request().Host
+	rss, err := s.generateRSSFromMemoList(ctx, memoList, baseURL, systemCustomizedProfile)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to generate rss").SetInternal(err)
+	}
+	c.Response().Header().Set(echo.HeaderContentType, echo.MIMEApplicationXMLCharsetUTF8)
+	return c.String(http.StatusOK, rss)
+}
 
-		systemCustomizedProfile, err := s.getSystemCustomizedProfile(ctx)
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to get system customized profile").SetInternal(err)
-		}
+// getUserRSS godoc
+//
+//	@Summary	Get RSS for a user
+//	@Tags		rss
+//	@Produce	xml
+//	@Param		id	path		int	true	"User ID"
+//	@Success	200	{object}	nil	"RSS"
+//	@Failure	400	{object}	nil	"User id is not a number"
+//	@Failure	500	{object}	nil	"Failed to get system customized profile | Failed to find memo list | Failed to generate rss"
+//	@Router		/u/{id}/rss.xml [GET]
+func (s *APIV1Service) getUserRSS(c echo.Context) error {
+	ctx := c.Request().Context()
+	id, err := util.ConvertStringToInt32(c.Param("id"))
+	if err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "User id is not a number").SetInternal(err)
+	}
 
-		normalStatus := store.Normal
-		memoFind := store.FindMemo{
-			CreatorID:      &id,
-			RowStatus:      &normalStatus,
-			VisibilityList: []store.Visibility{store.Public},
-		}
-		memoList, err := s.Store.ListMemos(ctx, &memoFind)
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find memo list").SetInternal(err)
-		}
+	systemCustomizedProfile, err := s.getSystemCustomizedProfile(ctx)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to get system customized profile").SetInternal(err)
+	}
 
-		baseURL := c.Scheme() + "://" + c.Request().Host
-		rss, err := s.generateRSSFromMemoList(ctx, memoList, baseURL, systemCustomizedProfile)
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to generate rss").SetInternal(err)
-		}
-		c.Response().Header().Set(echo.HeaderContentType, echo.MIMEApplicationXMLCharsetUTF8)
-		return c.String(http.StatusOK, rss)
-	})
+	normalStatus := store.Normal
+	memoFind := store.FindMemo{
+		CreatorID:      &id,
+		RowStatus:      &normalStatus,
+		VisibilityList: []store.Visibility{store.Public},
+	}
+	memoList, err := s.Store.ListMemos(ctx, &memoFind)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find memo list").SetInternal(err)
+	}
+
+	baseURL := c.Scheme() + "://" + c.Request().Host
+	rss, err := s.generateRSSFromMemoList(ctx, memoList, baseURL, systemCustomizedProfile)
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to generate rss").SetInternal(err)
+	}
+	c.Response().Header().Set(echo.HeaderContentType, echo.MIMEApplicationXMLCharsetUTF8)
+	return c.String(http.StatusOK, rss)
 }
 
 func (s *APIV1Service) generateRSSFromMemoList(ctx context.Context, memoList []*store.Memo, baseURL string, profile *CustomizedProfile) (string, error) {

api/v1/user_setting.go

@@ -78,6 +78,52 @@ type UpsertUserSettingRequest struct {
 	Value  string         `json:"value"`
 }
 
+func (s *APIV1Service) registerUserSettingRoutes(g *echo.Group) {
+	g.POST("/user/setting", s.createUserSetting)
+}
+
+// createUserSetting godoc
+//
+//	@Summary	Create user setting
+//	@Tags		user-setting
+//	@Accept		json
+//	@Produce	json
+//	@Param		body	body		UpsertUserSettingRequest	true	"Request object."
+//	@Success	200		{object}	store.UserSetting			"Created user setting"
+//	@Failure	400		{object}	nil							"Malformatted post user setting upsert request | Invalid user setting format"
+//	@Failure	401		{object}	nil							"Missing auth session"
+//	@Failure	500		{object}	nil							"Failed to upsert user setting"
+//	@Security	ApiKeyAuth
+//	@Router		/api/v1/user/setting [POST]
+func (s *APIV1Service) createUserSetting(c echo.Context) error {
+	ctx := c.Request().Context()
+	userID, ok := c.Get(auth.UserIDContextKey).(int32)
+	if !ok {
+		return echo.NewHTTPError(http.StatusUnauthorized, "Missing auth session")
+	}
+
+	userSettingUpsert := &UpsertUserSettingRequest{}
+	if err := json.NewDecoder(c.Request().Body).Decode(userSettingUpsert); err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post user setting upsert request").SetInternal(err)
+	}
+	if err := userSettingUpsert.Validate(); err != nil {
+		return echo.NewHTTPError(http.StatusBadRequest, "Invalid user setting format").SetInternal(err)
+	}
+
+	userSettingUpsert.UserID = userID
+	userSetting, err := s.Store.UpsertUserSetting(ctx, &store.UserSetting{
+		UserID: userID,
+		Key:    userSettingUpsert.Key.String(),
+		Value:  userSettingUpsert.Value,
+	})
+	if err != nil {
+		return echo.NewHTTPError(http.StatusInternalServerError, "Failed to upsert user setting").SetInternal(err)
+	}
+
+	userSettingMessage := convertUserSettingFromStore(userSetting)
+	return c.JSON(http.StatusOK, userSettingMessage)
+}
+
 func (upsert UpsertUserSettingRequest) Validate() error {
 	if upsert.Key == UserSettingLocaleKey {
 		localeValue := "en"
@@ -119,37 +165,6 @@ func (upsert UpsertUserSettingRequest) Validate() error {
 	return nil
 }
 
-func (s *APIV1Service) registerUserSettingRoutes(g *echo.Group) {
-	g.POST("/user/setting", func(c echo.Context) error {
-		ctx := c.Request().Context()
-		userID, ok := c.Get(auth.UserIDContextKey).(int32)
-		if !ok {
-			return echo.NewHTTPError(http.StatusUnauthorized, "Missing auth session")
-		}
-
-		userSettingUpsert := &UpsertUserSettingRequest{}
-		if err := json.NewDecoder(c.Request().Body).Decode(userSettingUpsert); err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post user setting upsert request").SetInternal(err)
-		}
-		if err := userSettingUpsert.Validate(); err != nil {
-			return echo.NewHTTPError(http.StatusBadRequest, "Invalid user setting format").SetInternal(err)
-		}
-
-		userSettingUpsert.UserID = userID
-		userSetting, err := s.Store.UpsertUserSetting(ctx, &store.UserSetting{
-			UserID: userID,
-			Key:    userSettingUpsert.Key.String(),
-			Value:  userSettingUpsert.Value,
-		})
-		if err != nil {
-			return echo.NewHTTPError(http.StatusInternalServerError, "Failed to upsert user setting").SetInternal(err)
-		}
-
-		userSettingMessage := convertUserSettingFromStore(userSetting)
-		return c.JSON(http.StatusOK, userSettingMessage)
-	})
-}
-
 func convertUserSettingFromStore(userSetting *store.UserSetting) *UserSetting {
 	return &UserSetting{
 		UserID: userSetting.UserID,

scripts/generate-api-documentation.cfg

+# This file is used by generate-api-documentation.ps1 and generate-api-documentation.sh
+
+# You should list aditional dirs here if the API grows
+SWAG_API_DIRS=./api/v1
+
+# Where general API info is documented
+SWAG_GENERAL_INFO=./server/server.go
+
+# Possible output files: go (docs.go), json (swagger.json), yaml (swagger.yaml)
+SWAG_OUTPUT_TYPES=go,yaml
+
+# Where generated files are outputted
+SWAG_OUTPUT=./api