Add more detailed information(swagger) for APIs

CB-Ladybug 사용자인 CB-webtool과 논의를 진행하다 보니 현재 CB-Ladybug REST API에 대한 설명 자료가 다소 부족하게 느끼고 있습니다. Swagger를 통해서 제공하는 API의 전체 목록이나 파라미터 형태 등 전체적인 윤곽을 파악하기는 유용하지만 실제 사용하려면 보다 자세한 정보가 필요한 것으로 파악됩니다.

Swagger 관련하여 조금 찾아보니 몇 가지 방법을 통해서 앞서 언급한 어려움을 다소 완화할 수 있을 것으로 생각됩니다.

swagger 포맷에서 해당 API의 @Param에 더 구체적인 설명을 작성합니다.

# src/rest-api/router/cluster.go
// CreateCluster
// @Tags Cluster
// @Summary Create Cluster
// @Description Create Cluster
// @ID CreateCluster
// @Accept json
// @Produce json
// @Param namespace path  string  true  "namespace"
// @Param json body model.ClusterReq true "ControlPlane.count를 3개이상 입력하면 ControlPlane이 고가용성을 제공합니다. 등"
// @Success 200 {object} model.Cluster
// @Router /ns/{namespace}/clusters [post]

swagger 포맷에서 {object} 형태인 경우 아래와 같이 해당 필드에 example 프로퍼티를 추가하여 부연 설명을 작성합니다.

# src/core/model/request.go
type Kubernetes struct {
NetworkCni       string `json:"networkCni" example:"kilo, xxx 등 선택"`
PodCidr          string `json:"podCidr" example:"172.168.1.0/24"`
ServiceCidr      string `json:"serviceCidr"`
ServiceDnsDomain string `json:"serviceDnsDomain"`
}

검토 부탁드립니다.

cloud-barista / cb-ladybug

Add more detailed information(swagger) for APIs #42