Cb-tumblebug: Issue: Swagger with REST APIs that operate differently according to query param

[jihoon-seo]

@seokho-son

예를 들어

[Call chain]

1. POST /:nsId/resources/image (src/api/rest/server/server.go)
2. func RestPostImage (src/api/rest/server/mcir/image.go)

이 기능은

1. POST /:nsId/resources/image?action=registerWithInfo 로 호출되면
   Request JSON body 를 TbImageInfo struct 로 Bind (unmarshal) 하고
2. POST /:nsId/resources/image?action=registerWithId 로 호출되면
   Request JSON body 를 TbImageReq struct 로 Bind (unmarshal) 합니다.

이는 func RestPostImage 안에서 if 문으로 구현되어 있습니다.

    action := c.QueryParam("action")
    fmt.Println("[POST Image requested action: " + action)
    /*
        if action == "create" {
            fmt.Println("[Creating Image]")
            content, _ := createImage(nsId, u)
            return c.JSON(http.StatusCreated, content)

        } else */
    if action == "registerWithInfo" {
        fmt.Println("[Registering Image with info]")
        u := &mcir.TbImageInfo{}
        if err := c.Bind(u); err != nil {
            return err
        }
        content, err := mcir.RegisterImageWithInfo(nsId, u)
        if err != nil {
            common.CBLog.Error(err)
            mapA := map[string]string{"message": err.Error()}
            return c.JSON(http.StatusFailedDependency, &mapA)
        }
        return c.JSON(http.StatusCreated, content)
    } else if action == "registerWithId" {
        fmt.Println("[Registering Image with ID]")
        u := &mcir.TbImageReq{}
        if err := c.Bind(u); err != nil {
            return err
        }
        //content, responseCode, body, err := RegisterImageWithId(nsId, u)
        content, err := mcir.RegisterImageWithId(nsId, u)
        if err != nil {
            common.CBLog.Error(err)
            //fmt.Println("body: ", string(body))
            //return c.JSONBlob(responseCode, body)
            mapA := map[string]string{"message": err.Error()}
            return c.JSON(http.StatusFailedDependency, &mapA)
        }
        return c.JSON(http.StatusCreated, content)
    }

---

그런데 Swagger 를 위한 주석에는
해당 내용 (Query param 에 따라 Request body 로 사용할 struct 가 달라짐) 을 기재할 수가 없는 것으로 보입니다.

...
// @Param registeringMethod query string true "registerWithInfo or registerWithId"
// @Param nsId path string true "Namespace ID"
// @Param imageInfo body mcir.TbImageInfo true "Details for an image object"
...

---

해결책으로는

• POST /:nsId/resources/image?action=registerWithInfo
• POST /:nsId/resources/image?action=registerWithId

이렇게 구분되어 있는 것을

• POST /:nsId/resources/registerImageWithInfo
• POST /:nsId/resources/registerImageWithId

이런 식으로 분리하는 안이 있습니다.
(REST API 의 URL 이 일반적인 REST API tradition 과 맞지 않기는 합니다.)

[issue-label-bot[bot]]

Issue-Label Bot is automatically applying the label bug to this issue, with a confidence of 0.54. Please mark this comment with :thumbsup: or :thumbsdown: to give our bot feedback!

Links: app homepage, dashboard and code for this bot.

[seokho-son]

@jihoon-seo 아래와 같은 방식으로 처리하면 어떨까요?
다만, response 도 쿼리 파라미터에 따라 다르게 하는 것은 되는지 모르겠습니다.

// PostNs godoc
// @Summary Create namespace
// @Description Create namespace by json RestPostNs
// @Tags Namespace
// @Accept  json
// @Produce  json
(요기) // @Param registerWithInfo body common.NsInfo true "Post Ns2"
(요기) // @Param registerWithId body common.NsInfo true "Post Ns"
// @Success 200 {object} common.NsInfo
// @Failure 404 {object} common.SimpleMsg
// @Failure 500 {object} common.SimpleMsg
// @Router /ns [post]

[jihoon-seo]

@seokho-son
이 방법도 좋은 것 같습니다.
이렇게 진행하겠습니다.

[jihoon-seo]

echo-swagger 용 comment 에

// @Router /ns/{nsId}/resources/image?action={registeringMethod} [post]
위와 같이 query param 사용법을 명시적으로 적어 주고 싶었는데
이렇게 하면

swag i

2020/07/07 15:50:42 ParseComment error in file api/rest/server/mcir/image.go :can not parse router comment "/ns/{nsId}/resources/image?action={registeringMethod} [post]"

이런 에러가 납니다.

---

따라서

// @Router /ns/{nsId}/resources/image [post]
이렇게 적어야 합니다. (query param 사용법을 명시적으로 적어 줄 수 없음)

[seokho-son]

@jihoon-seo 아래 방식을 통해서 처리할 수 있을 것 같습니다.
https://github.com/cloud-barista/cb-tumblebug/discussions/414#discussioncomment-546987
mcis get action 관련 API 파라미터는 처리가 된 것 같은데,

MCIR 쪽도 한 번 확인해봐주실 수 있을까요? 처리가 되어 있다면 ~ 해당 이슈는 close 하면될거 같습니다.. ^^

[seokho-son]

/close