Swagger 파일 생성

개요

우리가 알다시피, beego 프레임워크는 "bee"라는 명령 줄 도구를 통해 API를 명확하게 하는 swagger 파일을 생성하는 지원을 제공합니다. Casdoor도 beego를 기반으로 구축되었습니다. 그러나, 우리는 bee가 생성한 swagger 파일이 "@Tag" 라벨로 API를 분류하지 못했다는 것을 발견했습니다. 그래서, 우리는 이 기능을 구현하기 위해 원래의 bee를 수정했습니다.

주석 작성 방법

대부분의 규칙은 원래의 bee 주석 형식과 완전히 동일합니다. 유일한 차이점은 API가 "@Tag" 라벨에 따라 다른 그룹으로 나눠져야 한다는 것입니다. 따라서, 개발자들은 이 태그가 올바르게 추가되었는지 확인해야 합니다. 다음은 예시입니다:

// @Title Login
// @Tag Login API
// @Description login
// @Param   oAuthParams     query    string  true        "oAuth parameters"
// @Param   body    body   RequestForm  true        "Login information"
// @Success 200 {object} controllers.api_controller.Response The Response object
// @router /login [post]
func (c *ApiController) Login() {

같은 "@Tag" 라벨을 가진 API들은 같은 그룹에 놓이게 됩니다.

swagger 파일 생성 방법

0. 올바른 형식으로 API에 대한 주석을 작성합니다.

1. 이 저장소를 가져옵니다: https://github.com/casbin/bee.

2. 수정된 bee를 빌드합니다. 예를 들어, casbin/bee의 루트 디렉토리에서 다음 명령을 실행합니다:

   go build -o mybee .

3. mybee를 casdoor의 기본 디렉토리로 복사합니다.

4. 그 디렉토리에서 다음 명령을 실행합니다:

   mybee generate docs

5. (선택 사항) 특정 태그 또는 api에 대한 swagger 문서를 생성하려면 다음과 같은 예제 명령이 있습니다:

   mybee generate docs --tags "Adapter API"
   mybee generate docs --tags "Adapter API,Login API"
   mybee generate docs --apis "add-adapter"
   mybee generate docs --apis "add-adapter,delete-adapter"

   특히: 여러 태그/api가 제공될 때 구분자로 쉼표 ,만을 허용합니다.

그런 다음 새로운 swagger 파일이 생성되었다는 것을 알게 될 것입니다.