Swagger

설치

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

Usage

cd <project>

swag init && swag fmt

docs/
├── docs.go
├── swagger.json
└── swagger.yaml

Comments 형식

General API Info

• https://github.com/swaggo/swag#general-api-info

API Operation

• https://github.com/swaggo/swag#api-operation

@Accept, @Produce

• https://github.com/swaggo/swag#mime-types

// @Accept  <mime-types>
// @Produce <mime-types>

@Param

// @Param <param_name> <param_type> <data_type> <mandatory> "<comment>" [<attribute>]

Ex) // @Param user_id path int true "User ID"

• <param_type>
  • query
  • path
  • header
  • body
  • fromData
• <data_type>
  • string
  • integer
  • number
  • boolean
  • 사용자가 정의한 struct
• <attirbute>
  • https://github.com/swaggo/swag#attribute

정보

data_type으로 사용자 정의 struct를 사용할 때, attribute를 <key>:"<value>" 형식의 태그로 사용할 수 있습니다.

type sendEmailVerificationRequest struct {
	Email string `json:"email" binding:"required,email" validate:"required" format:"email"`
}

@Router

// @Router /<path> [<httpMethod>]

Ex) // @Router /examples/user/{user_id}/address [put]

@Success, @Failure, @Response

// @Success <status> {<schema_type>} <data_type> "<comment>"

// @Success <status> "<comment>"

@Header

// @Header <status> {<schema_type>} <data_type> "<comment>"

• <status>: ,로 구분하여 여러 status를 표시할 수 있습니다. default와 all 키워드도 있습니다.