API Document Update

REST API update guide

CB-TB는 Swagger를 통해서 소스코드를 기반으로 API 문서를 자동 생성함.

참고: echo-swagger 참고: swag cli

API를 변경하는 경우, 아래 절차에 따라서 API 문서 (Swagger API 형태) 업데이트가 필요.

1. swag 환경 구성

Download Swag for Go by using

go install github.com/swaggo/swag/cmd/swag

2. 소스코드에 API 관련 코멘트 입력

코멘트 입력 포멧 및 기존 API 코멘트를 예시로 참고하여 코멘트 수정

3. swag init 을 통해 API 문서 자동 생성

cb-tumblebug/src 이동하여 아래 커맨드 실행

make swag

또는

${HOME}/go/bin/swag init

4. 결과를 확인하고 PR에 포함

cb-tumblebug/tree/main/src/api/rest/docs 에 다음 파일들의 변경 사항 확인

• docs.go
• swagger.json
• swagger.yaml

참고: https://github.com/cloud-barista/cb-tumblebug/tree/main/src/api/rest/docs

별도의 커밋으로 PR에 포함.

단, 현재

https://github.com/cloud-barista/cb-tumblebug/blob/main/.github/workflows/make-swagger.yaml 워크플로우를 통해서

자동으로 API 문서 업데이트 PR이 생성되므로, 업데이트된 API 문서를 PR에 꼭 첨부할 필요는 없음.