배경

현재 API 가 외부에도 노출되어 있기 때문에 API 게이트웨이를 만들어서 특정 API 만 노출되도록 수정하려고 한다 그전에 API 를 정리하기 위해서 swagger 를 적용하기로 했다.

지금 echo 프레임워크 환경에서 swagger 를 설치하는 방법에 대해서 기록한다

적용 방법

1. 설치 1-1 go annoations 활용하기 위한 설치 go get -u github.com/swaggo/swag/cmd/swag

• (go 1.17 이상)go install github.com/swaggo/swag/cmd/swag@latest 1-2 echo 프레임워크를 사용한다면 echo 에서 동작하도록 하기 위한 설정 go get -u github.com/swaggo/echo-swagger 설치 하고 아래 코드를 추가

func main() {
    e := echo/New()
        ...
    e.GET("/swagger/*", echoSwagger.WrapHandler)
}

3. 각 API 에 annoations 추가한다

// @Summary
// @Description 개
// @Produce json
// @Param name path string true "name of the user"
// @Success 200 {object} map[string][]string
// @Router / [post]

4. /docs 생성하고 swag 실행

swag init 을 실행 우리코드느 main.go 가 아니라 application.go 로 쓰고 있어서 swag init -g application.go 처럼 실행코드를 지정햇다 docs 폴더가 생기고 내부에 swagger.json에서 ui 를 미리보기 할 수 있다 (질문) 이 명령을 매번 계속 실행해야 하나?yes 수정된 내용 적용되려면 실행해야함

4-1 Add General API annotations in main.go(application.go) file

// @title           Swagger Example API
// @version         1.0
// @description     This is a sample server celler server.
// @termsOfService  http://swagger.io/terms/

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html

// @host      localhost:8080
// @BasePath  /
// @Schemes http

func main() {

주석의 내용처럼 설정하고 init 실행

4-2 Bearer token 설정

• API key (as a header or a query string parameter) 지금은 임시로 config 환경변수에 추가해서 지정값이 로그인시 토큰값으로 오면 config 값을 불러와 토큰으로 사용

const (
	noTokenAccessDocu = "/api/docu" // 토큰 없이 접근 가능한 페이지
)

e.GET(noTokenAccessDocu+"/*", echoSwagger.WrapHandler)
// swagger/* 내용을 /api/docu/* 로 수정해서 사용했음 (원하는 url로)

아래 태그를 써서..설정하는 다른 방법도 있을 거 같다 ..

• @securityDefinitions.basic BasicAuth
• @securityDefinitions.apikey Bearer

5. main.go(application.go) 파일에 import 필수 _ "test-service/docs"" *test-service 는 프로젝트명)

6. go run main.go 실행해서 코드 실행하고 아래 url 로 접속

http://localhost:8000/api/docu/index.html URL 접속

참고

https://wookiist.dev/103 https://swagger.io/ https://stackoverflow.com/questions/65691081/swagger-generation-is-ignoring-securitydefiniton