在项目开发中，避免不了的写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

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