go echo框架引入swagger

go echo 框架引入 swagger

在项目开发中，避免不了的写 api 接口文档。这是一件费时费力的事情，因为接口可能随时变动，就要更新接口文档。引入 swagger 可以节省开发时间，减少开发者的工作量

1. 安装 swag

mac 为例, 其他系统大同小异

go 的版本 1.22

echo v4 (v4 以下版本好像不太行)

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

执行命令后，可以在 gobin 目录看到 swag，或者执行swag init 查看是否安装成功

2. 项目中引入 swagger

因为用的 echo 框架，所以在项目中安装echo-swagger

新建或者打开项目目录，在终端执行

echo-swagger 地址

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

3. 使用

1. 在 main.go 入口文件使用

   import(_ "your_project/docs" // docs is generated by Swag CLI, you have to import it.)
   
   // @title test
   // @version 1.0
   // @description test
   // @termsOfService http://swagger.io/terms/
   // @host http://127.0.0.1
   // @BasePath /v1
   func main() {cmd.Execute()
   }

2. 注册 swagger 路由

   e.GET("/swagger/*", echoSwagger.WrapHandler)
   
   e.Use(middleware.BodyDumpWithConfig(middleware.BodyDumpConfig{
       Skipper: nil,
       Handler: nil,
   }))
   
   func bodyDumpDefaultSkipper(c echo.Context) bool {if !strings.HasPrefix(c.Path(), "/v1/") && !strings.HasPrefix(c.Path(), "/swagger") {return true}
   return false
   }
   
   func bodyDumpHandler(context echo.Context, requestBody, responseBody []byte) {if !strings.HasPrefix(context.Path(), "/v1/") && !strings.HasPrefix(context.Path(), "/swagger") {return}
   uid := context.Get(em.SysTraceId).(string)
   
    e.GET("/ping", pingHandler)
    e.Logger.Fatal(":1234")
   }
   

3. example

// ping godoc
// @Summary 新增接口描述
// @Description 详细描述
// @Tags 测试路由 ping
// @Accept  json
// @Produce  json
// @Param paramName query string false " 参数描述 "
// @Success 200 {string} string "pong..."
// @Router /ping [get]
func pingHandler(c echo.Context) error {return c.JSON(http.StatusOK, "pong...")
}

4. 访问 http://127.0.0.1:1234/swagger/index.html

5. 编写 makefile
   如果想在 makefile 中使用 debug，需要安装 dlv

   go install github.com/go-delve/delve/cmd/dlv@latest

# makefile

# 项目名称
PROJECT_NAME := test

# 执行文件
EXECUTABLE := $(PROJECT_NAME)

# go 项目目录
SRC_DIR := $(CURRENT_DIR)

# Swagger 命令
SWAG := swag

# Go 命令
GO := go
# 编译命令
.PHONY: build

build:
    $(GO) build -o $(EXECUTABLE)

# 运行 Swagger 命令生成文档
.PHONY: swag
swag:
    $(SWAG) init -g $(SRC_DIR)/main.go

# 清理生成的文件
.PHONY: clean
clean:
    $(GO) clean
    rm -f $(EXECUTABLE)
    rm -rf docs

# 运行应用程序
.PHONY: run
run:
    $(GO) run main.go -c=config.yaml

# 调试程序 debug
.PHONY: debug
debug:
    @dlv debug main.go --headless --listen=:9190 --log -- -config=$(CONFIG_FILE)

# 默认目标
.PHONY: all
all: clean swag build run