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
新建或者打开项目目录,在终端执行
go get -u github.com/swaggo/echo-swagger
3. 使用
-
在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() }
-
注册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") }
-
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...")
}
- 编写makefile
如果想在makefile中使用debug,需要安装dlvgo 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