首页 GoEchogo echo框架引入swagger

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...")
}
  1. 访问 http://127.0.0.1:1234/swagger/index.html

http://images.caixiaoxin.cn/echo_swagger.png

  1. 编写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