Location of Swagger doc files

[jihoon-seo]

• Related issue: Location of Swagger doc files cb-tumblebug#614
• Related PR: Move Swagger doc files cb-tumblebug#616

What would you like to be enhanced
: Location of Swagger doc files

Why is this needed
: 현재 Swagger docs 는 REST API 에 대해서만 제공되고 있음

Proposed solution
: Move cb-ladybug/src/docs/ to cb-ladybug/src/rest-api/docs/

[영향을 미치기 때문에 추가로 변경해야 하는 곳들의 후보]

• https://github.com/cloud-barista/docs
• https://github.com/cloud-barista/cloud-barista.github.io
• https://github.com/cloud-barista/cb-ladybug-api-web
• ...

[sykim-etri]

@jihoon-seo CB-TB에서는 grpc와 관련한 API는 어떻게 문서화하고 있나요?

[jihoon-seo]

REST API 만 Swagger 를 이용하여 문서화하고 있고,
gRPC 에 대해서는 문서화하지 않고 있습니다. 😊

[sykim-etri]

gRPC API가 실질적으로는 REST API와 동일할 것으로 예상되긴 한데.. 당장 rest-api/docs로 옮기는 것이 의미가 있을까요? API간 차이가 생긴다면 옮기는 것이 맞겠지만. gRPC API를 문서화할 방법이 있을지 고민해봐야 할 부분인 것 같습니다.

[seokho-son]

gRPC API 문서화까지 이중으로 한다면.. 관리 포인트가 또 늘어나서 난감하긴 하네요..

해당 docs 디렉토리 위치는 특별히 중요한 문제는 아니라
각 저장소의 메인테이너께서 결정하시면 될거라 생각합니다... ^^

[powerkimhub]

통상 아래와 같이 언어별 제공 tool을 사용합니다. (REST, gRPC는 언어가 아님)
현재는 FW별로 진행 속도가 다르니, FW별 주요도에 따라 정리해가시면 되겠습니다.

• java API docs => javadoc
• go API docs => godoc (our gRPC)
  • https://blog.golang.org/godoc
• REST => swagger (one of method)