TIL 12 - Swagger - 문서 자동화 도구(Golang)

Swagger - 문서 자동화 도구

GitHub - swaggo/swag: Automatically generate RESTful API documentation with Swagger 2.0 for Go.

• 특징
  • 작업, 개발 내역 API의 기능, 명세 관리할 수 있는 도구
  • swagger를 통한 커뮤니케이션
  • 파라미터를 통한 테스트
  • 문서 현행화로 인한 문서화 작업에 드는 비용이 줄어드는 이점이 있다.
• 사용 방법

  go get -u github.com/swaggo/swag/cmd/swag
  ## go 1.17 이상
  go install github.com/swaggo/swag/cmd/swag@latest
  ## 설치 경로 확인
  GOPATH/bin
  
  ## 사용 시
  swag init 

  • 사용 패키지

    // gin 프레임워크에서 사용하는 swagger 미들웨어 패키지
    go get -u github.com/swaggo/gin-swagger
    // swagger embed files
    go get -u github.com/swaggo/files

  • 관용 문구

    	e := gin.Default()
    	e.Use(gin.Logger())
    	e.Use(gin.Recovery())
    	e.Use(CORS())
    
    	e.GET("/health")
    	//swagger 핸들러 미들웨어에 등록
    	e.GET("/swagger/:any", ginSwg.WrapHandler(swgFiles.Handler)) 
    	docs.SwaggerInfo.Host = "localhost" //swagger 정보 등록
    	account := e.Group("acc/v01", liteAuth())
    	{
    		account.GET("/ok", p.ct.GetOK)
    	}

  • swagger comment 작성(아래에서 자세히 작성) @Summary : 해당 API에 대한 간단 요약
    @Description : 해당 기능에 대한 설명
    @name : API 이름
    @Accept : API 입력 형태(txt, json, etc...)
    @Produce : API 출력 형태(txt, json, etc...)
    @Param : API 사용 파라메터 및 타입
    @Router : URI 정보 및 [메소드]
    @Success : 응답코드 및 응답 객체

    // GetOK godoc
    // @Summary call GetOK, return ok by json.
    // @Description api test를 위한 기능.
    // @name GetOK
    // @Accept  json
    // @Produce  json
    // @Param name path string true "User name"
    // @Router /acc/v01/ok [get]
    // @Success 200 {object} Controller
    func (p *Controller) GetOK(c *gin.Context) {
    	c.JSON(200, gin.H{"msg": "ok"})
    	return
    }

  • 로딩 화면

    > go run main.go
    [GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
     - using env:   export GIN_MODE=release
     - using code:  gin.SetMode(gin.ReleaseMode)
    
    [GIN-debug] GET    /health                   --> lecture/go-swag/controller.(*Controller).GetOK-fm (4 handlers)
    [GIN-debug] GET    /swagger/:any             --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (4 handlers)
    [GIN-debug] GET    /acc/v01/ok               --> lecture/go-swag/controller.(*Controller).GetOK-fm (5 handlers)

  • 확인
    • 웹사이트에서 확인 가능
      • 실 서비스에서는 swagger 비활성화 후 배포
      • http://localhost:8080/swagger/index.html
  • swagger가 수정되면 swag init을 해줘야한다.

파라미터 사용법

• @Summary : 해당 API에 대한 간단 요약
• @Router : URI 정보 및 [메소드]

  // GetOK godoc
  // @Summary call GetOK, return ok by json.
  // @Router /acc/v01/ok [get]
  func (p *Controller) GetOK(c *gin.Context) {
  	c.JSON(200, gin.H{"msg": "ok"})
  	return
  }

  
  
• @Description : 해당 기능에 대한 설명

  // GetOK godoc
  // @Summary call GetOK, return ok by json.
  // @Description api test를 위한 기능.
  // @Router /acc/v01/ok [get]
  func (p *Controller) GetOK(c *gin.Context) {
  	c.JSON(200, gin.H{"msg": "ok"})
  	return
  }

  
  
• @name : API 이름

  // GetOK godoc
  // @Summary call GetOK, return ok by json.
  // @Description api test를 위한 기능.
  // @name GetOK
  // @Router /acc/v01/ok [get]
  func (p *Controller) GetOK(c *gin.Context) {
  	c.JSON(200, gin.H{"msg": "ok"})
  	return
  }

• @Accept : API 입력 형태(txt, json, etc...)

  // GetOK godoc
  // @Summary call GetOK, return ok by json.
  // @Accept  json
  // @Router /acc/v01/ok [get]
  func (p *Controller) GetOK(c *gin.Context) {
  	c.JSON(200, gin.H{"msg": "ok"})
  	return
  }

• @Produce : API 출력 형태(txt, json, etc...)

  // GetOK godoc
  // @Summary call GetOK, return ok by json.
  // @Description api test를 위한 기능.
  // @Produce  json
  // @Router /acc/v01/ok [get]
  func (p *Controller) GetOK(c *gin.Context) {
  	c.JSON(200, gin.H{"msg": "ok"})
  	return
  }

• @Param : API 사용 파라메터 및 타입

  @Param [param name] [param type] [data type] [is mandatory] [comment] [attribute(optional)]

  // @Param pnum path string true "PNUM"
  func (p *Controller) GetOK(c *gin.Context) {
  	c.JSON(200, gin.H{"msg": "ok"})
  	return
  }

• @Success : 응답코드 및 응답 객체

  // GetOK godoc
  // @Summary call GetOK, return ok by json.
  // @Description api test를 위한 기능.
  // @Router /acc/v01/ok [get]
  // @Success 200 {object} Controller
  func (p *Controller) GetOK(c *gin.Context) {
  	c.JSON(200, gin.H{"msg": "ok"})
  	return
  }