mirror of
https://github.com/usememos/memos.git
synced 2025-06-05 22:09:59 +02:00
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
This commit is contained in:
Lincoln Nogueira
GitHub
@@ -63,182 +63,238 @@ type UpdateStorageRequest struct {
|
||||
}
|
||||
|
||||
func (s *APIV1Service) registerStorageRoutes(g *echo.Group) {
|
||||
g.POST("/storage", 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")
|
||||
}
|
||||
g.GET("/storage", s.getStorageList)
|
||||
g.POST("/storage", s.createStorage)
|
||||
g.DELETE("/storage/:storageId", s.deleteStorage)
|
||||
g.PATCH("/storage/:storageId", s.updateStorage)
|
||||
}
|
||||
|
||||
user, err := s.Store.GetUser(ctx, &store.FindUser{
|
||||
ID: &userID,
|
||||
})
|
||||
// getStorageList godoc
|
||||
//
|
||||
// @Summary Get a list of storages
|
||||
// @Tags storage
|
||||
// @Produce json
|
||||
// @Success 200 {object} []store.Storage "List of storages"
|
||||
// @Failure 401 {object} nil "Missing user in session | Unauthorized"
|
||||
// @Failure 500 {object} nil "Failed to find user | Failed to convert storage"
|
||||
// @Security ApiKeyAuth
|
||||
// @Router /api/v1/storage [GET]
|
||||
func (s *APIV1Service) getStorageList(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")
|
||||
}
|
||||
|
||||
user, err := s.Store.GetUser(ctx, &store.FindUser{
|
||||
ID: &userID,
|
||||
})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find user").SetInternal(err)
|
||||
}
|
||||
// We should only show storage list to host user.
|
||||
if user == nil || user.Role != store.RoleHost {
|
||||
return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
|
||||
}
|
||||
|
||||
list, err := s.Store.ListStorages(ctx, &store.FindStorage{})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find storage list").SetInternal(err)
|
||||
}
|
||||
|
||||
storageList := []*Storage{}
|
||||
for _, storage := range list {
|
||||
storageMessage, err := ConvertStorageFromStore(storage)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find user").SetInternal(err)
|
||||
}
|
||||
if user == nil || user.Role != store.RoleHost {
|
||||
return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to convert storage").SetInternal(err)
|
||||
}
|
||||
storageList = append(storageList, storageMessage)
|
||||
}
|
||||
return c.JSON(http.StatusOK, storageList)
|
||||
}
|
||||
|
||||
create := &CreateStorageRequest{}
|
||||
if err := json.NewDecoder(c.Request().Body).Decode(create); err != nil {
|
||||
// createStorage godoc
|
||||
//
|
||||
// @Summary Create storage
|
||||
// @Tags storage
|
||||
// @Accept json
|
||||
// @Produce json
|
||||
// @Param body body CreateStorageRequest true "Request object."
|
||||
// @Success 200 {object} store.Storage "Created storage"
|
||||
// @Failure 400 {object} nil "Malformatted post storage request"
|
||||
// @Failure 401 {object} nil "Missing user in session"
|
||||
// @Failure 500 {object} nil "Failed to find user | Failed to create storage | Failed to convert storage"
|
||||
// @Security ApiKeyAuth
|
||||
// @Router /api/v1/storage [POST]
|
||||
func (s *APIV1Service) createStorage(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")
|
||||
}
|
||||
|
||||
user, err := s.Store.GetUser(ctx, &store.FindUser{
|
||||
ID: &userID,
|
||||
})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find user").SetInternal(err)
|
||||
}
|
||||
if user == nil || user.Role != store.RoleHost {
|
||||
return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
|
||||
}
|
||||
|
||||
create := &CreateStorageRequest{}
|
||||
if err := json.NewDecoder(c.Request().Body).Decode(create); err != nil {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post storage request").SetInternal(err)
|
||||
}
|
||||
|
||||
configString := ""
|
||||
if create.Type == StorageS3 && create.Config.S3Config != nil {
|
||||
configBytes, err := json.Marshal(create.Config.S3Config)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post storage request").SetInternal(err)
|
||||
}
|
||||
configString = string(configBytes)
|
||||
}
|
||||
|
||||
configString := ""
|
||||
if create.Type == StorageS3 && create.Config.S3Config != nil {
|
||||
configBytes, err := json.Marshal(create.Config.S3Config)
|
||||
storage, err := s.Store.CreateStorage(ctx, &store.Storage{
|
||||
Name: create.Name,
|
||||
Type: create.Type.String(),
|
||||
Config: configString,
|
||||
})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to create storage").SetInternal(err)
|
||||
}
|
||||
storageMessage, err := ConvertStorageFromStore(storage)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to convert storage").SetInternal(err)
|
||||
}
|
||||
return c.JSON(http.StatusOK, storageMessage)
|
||||
}
|
||||
|
||||
// deleteStorage godoc
|
||||
//
|
||||
// @Summary Delete a storage
|
||||
// @Tags storage
|
||||
// @Produce json
|
||||
// @Param storageId path int true "Storage ID"
|
||||
// @Success 200 {boolean} true "Storage deleted"
|
||||
// @Failure 400 {object} nil "ID is not a number: %s | Storage service %d is using"
|
||||
// @Failure 401 {object} nil "Missing user in session | Unauthorized"
|
||||
// @Failure 500 {object} nil "Failed to find user | Failed to find storage | Failed to unmarshal storage service id | Failed to delete storage"
|
||||
// @Security ApiKeyAuth
|
||||
// @Router /api/v1/storage/{storageId} [DELETE]
|
||||
//
|
||||
// NOTES:
|
||||
// - error message "Storage service %d is using" probably should be "Storage service %d is in use".
|
||||
func (s *APIV1Service) deleteStorage(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")
|
||||
}
|
||||
|
||||
user, err := s.Store.GetUser(ctx, &store.FindUser{
|
||||
ID: &userID,
|
||||
})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find user").SetInternal(err)
|
||||
}
|
||||
if user == nil || user.Role != store.RoleHost {
|
||||
return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
|
||||
}
|
||||
|
||||
storageID, err := util.ConvertStringToInt32(c.Param("storageId"))
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("storageId"))).SetInternal(err)
|
||||
}
|
||||
|
||||
systemSetting, err := s.Store.GetSystemSetting(ctx, &store.FindSystemSetting{Name: SystemSettingStorageServiceIDName.String()})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find storage").SetInternal(err)
|
||||
}
|
||||
if systemSetting != nil {
|
||||
storageServiceID := DatabaseStorage
|
||||
err = json.Unmarshal([]byte(systemSetting.Value), &storageServiceID)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to unmarshal storage service id").SetInternal(err)
|
||||
}
|
||||
if storageServiceID == storageID {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Storage service %d is using", storageID))
|
||||
}
|
||||
}
|
||||
|
||||
if err = s.Store.DeleteStorage(ctx, &store.DeleteStorage{ID: storageID}); err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to delete storage").SetInternal(err)
|
||||
}
|
||||
return c.JSON(http.StatusOK, true)
|
||||
}
|
||||
|
||||
// updateStorage godoc
|
||||
//
|
||||
// @Summary Update a storage
|
||||
// @Tags storage
|
||||
// @Produce json
|
||||
// @Param storageId path int true "Storage ID"
|
||||
// @Param patch body UpdateStorageRequest true "Patch request"
|
||||
// @Success 200 {object} store.Storage "Updated resource"
|
||||
// @Failure 400 {object} nil "ID is not a number: %s | Malformatted patch storage request | Malformatted post storage request"
|
||||
// @Failure 401 {object} nil "Missing user in session | Unauthorized"
|
||||
// @Failure 500 {object} nil "Failed to find user | Failed to patch storage | Failed to convert storage"
|
||||
// @Security ApiKeyAuth
|
||||
// @Router /api/v1/storage/{storageId} [PATCH]
|
||||
func (s *APIV1Service) updateStorage(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")
|
||||
}
|
||||
|
||||
user, err := s.Store.GetUser(ctx, &store.FindUser{
|
||||
ID: &userID,
|
||||
})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find user").SetInternal(err)
|
||||
}
|
||||
if user == nil || user.Role != store.RoleHost {
|
||||
return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
|
||||
}
|
||||
|
||||
storageID, err := util.ConvertStringToInt32(c.Param("storageId"))
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("storageId"))).SetInternal(err)
|
||||
}
|
||||
|
||||
update := &UpdateStorageRequest{}
|
||||
if err := json.NewDecoder(c.Request().Body).Decode(update); err != nil {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, "Malformatted patch storage request").SetInternal(err)
|
||||
}
|
||||
storageUpdate := &store.UpdateStorage{
|
||||
ID: storageID,
|
||||
}
|
||||
if update.Name != nil {
|
||||
storageUpdate.Name = update.Name
|
||||
}
|
||||
if update.Config != nil {
|
||||
if update.Type == StorageS3 {
|
||||
configBytes, err := json.Marshal(update.Config.S3Config)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post storage request").SetInternal(err)
|
||||
}
|
||||
configString = string(configBytes)
|
||||
configString := string(configBytes)
|
||||
storageUpdate.Config = &configString
|
||||
}
|
||||
}
|
||||
|
||||
storage, err := s.Store.CreateStorage(ctx, &store.Storage{
|
||||
Name: create.Name,
|
||||
Type: create.Type.String(),
|
||||
Config: configString,
|
||||
})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to create storage").SetInternal(err)
|
||||
}
|
||||
storageMessage, err := ConvertStorageFromStore(storage)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to convert storage").SetInternal(err)
|
||||
}
|
||||
return c.JSON(http.StatusOK, storageMessage)
|
||||
})
|
||||
|
||||
g.PATCH("/storage/:storageId", 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")
|
||||
}
|
||||
|
||||
user, err := s.Store.GetUser(ctx, &store.FindUser{
|
||||
ID: &userID,
|
||||
})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find user").SetInternal(err)
|
||||
}
|
||||
if user == nil || user.Role != store.RoleHost {
|
||||
return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
|
||||
}
|
||||
|
||||
storageID, err := util.ConvertStringToInt32(c.Param("storageId"))
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("storageId"))).SetInternal(err)
|
||||
}
|
||||
|
||||
update := &UpdateStorageRequest{}
|
||||
if err := json.NewDecoder(c.Request().Body).Decode(update); err != nil {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, "Malformatted patch storage request").SetInternal(err)
|
||||
}
|
||||
storageUpdate := &store.UpdateStorage{
|
||||
ID: storageID,
|
||||
}
|
||||
if update.Name != nil {
|
||||
storageUpdate.Name = update.Name
|
||||
}
|
||||
if update.Config != nil {
|
||||
if update.Type == StorageS3 {
|
||||
configBytes, err := json.Marshal(update.Config.S3Config)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, "Malformatted post storage request").SetInternal(err)
|
||||
}
|
||||
configString := string(configBytes)
|
||||
storageUpdate.Config = &configString
|
||||
}
|
||||
}
|
||||
|
||||
storage, err := s.Store.UpdateStorage(ctx, storageUpdate)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to patch storage").SetInternal(err)
|
||||
}
|
||||
storageMessage, err := ConvertStorageFromStore(storage)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to convert storage").SetInternal(err)
|
||||
}
|
||||
return c.JSON(http.StatusOK, storageMessage)
|
||||
})
|
||||
|
||||
g.GET("/storage", 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")
|
||||
}
|
||||
|
||||
user, err := s.Store.GetUser(ctx, &store.FindUser{
|
||||
ID: &userID,
|
||||
})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find user").SetInternal(err)
|
||||
}
|
||||
// We should only show storage list to host user.
|
||||
if user == nil || user.Role != store.RoleHost {
|
||||
return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
|
||||
}
|
||||
|
||||
list, err := s.Store.ListStorages(ctx, &store.FindStorage{})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find storage list").SetInternal(err)
|
||||
}
|
||||
|
||||
storageList := []*Storage{}
|
||||
for _, storage := range list {
|
||||
storageMessage, err := ConvertStorageFromStore(storage)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to convert storage").SetInternal(err)
|
||||
}
|
||||
storageList = append(storageList, storageMessage)
|
||||
}
|
||||
return c.JSON(http.StatusOK, storageList)
|
||||
})
|
||||
|
||||
g.DELETE("/storage/:storageId", 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")
|
||||
}
|
||||
|
||||
user, err := s.Store.GetUser(ctx, &store.FindUser{
|
||||
ID: &userID,
|
||||
})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find user").SetInternal(err)
|
||||
}
|
||||
if user == nil || user.Role != store.RoleHost {
|
||||
return echo.NewHTTPError(http.StatusUnauthorized, "Unauthorized")
|
||||
}
|
||||
|
||||
storageID, err := util.ConvertStringToInt32(c.Param("storageId"))
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("ID is not a number: %s", c.Param("storageId"))).SetInternal(err)
|
||||
}
|
||||
|
||||
systemSetting, err := s.Store.GetSystemSetting(ctx, &store.FindSystemSetting{Name: SystemSettingStorageServiceIDName.String()})
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to find storage").SetInternal(err)
|
||||
}
|
||||
if systemSetting != nil {
|
||||
storageServiceID := DatabaseStorage
|
||||
err = json.Unmarshal([]byte(systemSetting.Value), &storageServiceID)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to unmarshal storage service id").SetInternal(err)
|
||||
}
|
||||
if storageServiceID == storageID {
|
||||
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Storage service %d is using", storageID))
|
||||
}
|
||||
}
|
||||
|
||||
if err = s.Store.DeleteStorage(ctx, &store.DeleteStorage{ID: storageID}); err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to delete storage").SetInternal(err)
|
||||
}
|
||||
return c.JSON(http.StatusOK, true)
|
||||
})
|
||||
storage, err := s.Store.UpdateStorage(ctx, storageUpdate)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to patch storage").SetInternal(err)
|
||||
}
|
||||
storageMessage, err := ConvertStorageFromStore(storage)
|
||||
if err != nil {
|
||||
return echo.NewHTTPError(http.StatusInternalServerError, "Failed to convert storage").SetInternal(err)
|
||||
}
|
||||
return c.JSON(http.StatusOK, storageMessage)
|
||||
}
|
||||
|
||||
func ConvertStorageFromStore(storage *store.Storage) (*Storage, error) {
|
||||
|
||||
Reference in New Issue
Block a user