Enhancement for Swagger API documentation

[seokho-son]

현황

TB는 API를 코드 코멘트 기반으로 생성된, Swagger API 문서로 제공하고 있음 (Github page로 호스팅)

https://cloud-barista.github.io/cb-tumblebug-api-web/?url=https://raw.githubusercontent.com/cloud-barista/cb-tumblebug/master/src/docs/swagger.yaml

이슈

해당 Swagger API 문서에는 몇 가지 측면에서 개선이 필요해 보임

• API의 상태 또는 용도가 명시되지 않음 (deprecated, beta, alpha, under-development), (for user, for developer, for admin, ...)
• API의 각 파라미터에 대한 상세 설명 또는 예시가 없음
• API의 용도 설명이 일부 빈약함

[seokho-son]

Ref) #189

Swagger 를 통한 API 자동 문서화

• Swaggo (Automatically generate RESTful API documentation with Swagger 2.0 for Go)을 사용하여 API 문서를 생성할 수 있도록 코드를 제공함.
  • Swaggo 지원을 위해 ECHO를 ECHO4로 업그레이드 함. (ECHO4 가 최신 Stable임)
• API 문서가 Echo REST 서버에서 동작함.
  • 텀블벅 서버(REST) 실행 후, 접속: http://localhost:1323/swagger/index.html
• Namespace 관련 API 리소스에 대해 예제 코드 개발.
  • model 정리 필요
  • 애러코드 정리 필요

Golang의 ECHO를 위한 Swaggo 설치 및 사용 방법

• https://github.com/swaggo/echo-swagger 참고
  • cb-tumblebug/src 에서 ~/go/bin/swag init 을 수행하면, 소스코드 내의 annotation을 활용하여 swagger api 문서가 자동 생성됨
  • 텀블벅 소스빌드 및 서버 실행 필요
  • 텀블벅 서버(REST) 실행 후, 접속: http://localhost:1323/tumblebug/swagger/index.html

[seokho-son]

https://github.com/swaggo/swag#available
을 활용하면, API의 각 파라미터에 대한 명세가 가능

예를 들어, struct에 다음을 추가하면,
// InstallMonAgent Option for CB-Dragonfly agent installation ([yes/no] default:yes)
InstallMonAgent string json:"installMonAgent" example:"[yes, no]" default:"yes" // yes or no

type TbMcisReq struct {
	Name           string    `json:"name"`
	Vm             []TbVmReq `json:"vm"`
	Placement_algo string    `json:"placement_algo"`

	// InstallMonAgent Option for CB-Dragonfly agent installation ([yes/no] default:yes)
	InstallMonAgent string `json:"installMonAgent" example:"[yes, no]" default:"yes"` // yes or no

	Description string `json:"description"`
	Label       string `json:"label"`
}

API 문서에서는 다음과 같이 표시됨.

[seokho-son]

다중 쿼리 파라미터 항목 추가 방법 예시
https://github.com/cloud-barista/cb-tumblebug/pull/422/files#diff-0f0ff9d9ade9ac1f0d1a993ef2d64adab0330ef50ec77c3f177369ddcb24229aR63