sentimental programmer: swag

다음과 같은 api 를 swag(https://github.com/swaggo/swag)로 문서 페이지를 생성했다.

// @Tags user

// @Router /users/aaa [get]

func (ctx *MyCtx) GetUserAAA(gc *gin.Context) ...

// @Tags user/item

// @Router /users/aaa [get]

func (ctx *MyCtx) GetUserItemAAA(gc *gin.Context) ...

// @Tags user/item

// @Router /users/aaa [post]

func (ctx *MyCtx) CreateUserItemAAA(gc *gin.Context) ...

생성된 swag api url을 각각 다음과 같이 되는데

1. http://localhost:8080/docs/index.html#/user/get_aaa

2. http://localhost:8080/docs/index.html#/user%2item/get_aaa

3. http://localhost:8080/docs/index.html#/user%2item/post_user_aaa

1번 링크는 해당 #(id)까지 스크롤 되어 해당 api 위치로 이동 되지만

2,3번 처럼 tags aa/bb 인 경우 해당 # 로 이동되지는 않는다.

Tags 이름에 / 처리가 되지않아 Tags 이름에서 / 를 -,_,. 등으로 변경해야 된다.

// @Tags user-item 또는 user_item 또는 user.item

기본적으로 #(id)는 {method)_{router_path} 처럼 _ 로 자동으로 생성된다.

만약 id 이름을 변경하고 싶다면 @ID 를 직접 명시해서 swag 를 생성하면 된다(-,_등 상관없이 원하는 값으로 설정하면 된다.)

// @ID get_user__aaa__bbb

이제 swag init 으로 swagger.json, swagger.yaml 생성해 보면

다음과 같이 operationId 필드가 추가되고 # 링크도 해당 부분으로 스크롤된다.

"operationId": "get_user__aaa__bbb",

# .go 파일에서 swag comment 작성 후 swag fmt 하면 다음과 같이 주석을 보기 좋게 간격을 띄워 준다.

# 그런데 vim, vscode 등에서 저장하면 gofmt 이 동작하며 다음과 같이 주석 앞쪽을 공백으로 바꾸면서 간격이 흐트러진다.

# 이상태에선 swag fmt 해도 포맷팅이 되지 않는다.

# 이상태에서 탭 부분을 수정 후 swag fmt 하면 포맷팅돼 위 화면처럼 된다.

# vim 등에서 저장(gofmt 으로 주석이 포맷팅)시 swag fmt 부분을 유지하려면

# 다음과 같이 맨위 주석과 공백 주석을 추가하면 gofmt 해도 이 swag 주석 부분이 변경되지 않는다.

#####

# default, enum 등의 속성 사용 예시

// @Param enumstring query string false "string enums" Enums(A, B, C)

// @Param enumint query int false "int enums" Enums(1, 2, 3)

// @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3)

// @Param string query string false "string valid" minlength(5) maxlength(10)

// @Param int query int false "int valid" minimum(1) maximum(10)

// @Param default query string false "string default" default(A)

// @Param example query string false "string example" example(string)

// @Param collection query []string false "string collection" collectionFormat(multi)

// @Param extensions query []string false "string collection" extensions(x-example=test,x-nullable)