[Golang] RESful API Document 생성

이번 포스팅은 go에서 API Document를 생성하고,

사용하는 방법에 관한 포스팅입니다.

 

 

 

 

사용한 깃 라이브러리

github.com/swaggo/echo-swagger

swaggo/echo-swagger

 

echo-swagger 환경 세팅

swag 라이브러리 다운

go get을 이용하여 필요한 라이브러리를 다운로드

$ go get -u github.com/swaggo/swag/cmd/swag

 

그 외 다양한 설정 값

swag int

프로젝트의 루트 폴더로 접근한 뒤 아래 코드 실행

>> 중요! 꼭 현재 진행하는 프로젝트의 main.go 파일이 있는 곳에서 실행

$ swag init

 

폴더/코드 파일 생성 확인

위 코드를 실행시키면, 해당 위치에 docs 폴더가 생성된다

해당 폴더에 접근하면, docs.go를 포함한 3개의 파일이 생성된다.

실행시키는 시점을 기준으로 api document가 생성되기 때문에, 수정사항이 있을 경우 다시 swag init을 해줘야 한다.

 

echo-swagger 다운로드

echo에서 swagger가 미들웨어로써 동작할 수 있게 하는 라이브러리를 다운

$ go get -u github.com/swaggo/echo-swagger

 

실제 코드 사용

package main

import (
	"github.com/labstack/echo/v4"
	"github.com/swaggo/echo-swagger"

	_ "github.com/[각자프로젝트_위치]/docs"
)

// @title API Document 
// @version 0.0.1
// @description this is sample document

func main() {
	e := echo.New()

	e.GET("/swagger/*", echoSwagger.WrapHandler)

	e.Logger.Fatal(e.Start(":1323"))
}

 

> import 할 때 docs는 꼭 자신이 새로 생성한 docs의 경로로 해야 한다.

> 정해진 규격을 사용하여 api 문서를 작성한다

> //@ 형태로 작성한다.

 

API 문서화

문서화에 필요한 코멘트 작성 법은 아래를 참고

github.com/swaggo/swag#declarative-comments-format

swaggo/swag

 

실제 구동 화면

localhost:1323/swagger/index.html 로 접속한다 (접속 주소는 main.go에서 변경 가능)