go-zero 对接 swagger 并自动生成接口文档,核心做法是在 go.mod 中引入 github.com/zeromicro/go-zero 依赖,并在代码中使用 goctl api go -c 命令生成带有 swagger 注解的 go 代码。这样生成的代码在启动时会自动解析注释,通过内置的 http 服务暴露 /swagger/json 接口,前端页面则通过 /swagger/web 访问。

如何配置 goctl 生成带注解的代码
使用 goctl api go -c 命令是生成兼容 Swagger 代码的标准方式。该命令会扫描 .api 文件,根据其中的路由定义和结构体标签,自动在生成的 .go 文件中插入 @doc、@summary 等 Swagger 标准注解。开发者只需确保 API 定义文件中的字段描述清晰,即可实现文档内容的自动化填充。

module myapp go 1.20 require github.com/zeromicro/go-zero v2.3.1
假设有一个 user.api 文件:
type UserRequest {
Name string `json:"name"` // 用户姓名
}
service user-api {
@handler CreateUser
post /user/create (UserRequest) returns (UserResponse)
}
执行以下命令生成代码:
goctl api go -api user.api -dir . -c
生成的代码中将包含如下注释:
// @title User API
// @version 1.0
// @description User management service
// @host localhost:8080
// @BasePath /
// CreateUser godoc
// @Summary Create a new user
// @Description Create a new user with name
// @Accept json
// @Produce json
// @Param body body UserRequest true "User info"
// @Success 200 {object} UserResponse
// @Router /user/create [post]
如何在项目中启用 Swagger 服务
在生成的代码中,Swagger 服务通常由框架内部自动注册。开发者需要在 main.go 或启动逻辑中确保服务器正常启动。Go-Zero 的 rest.Server 会在启动时自动挂载 Swagger 相关的路由。无需额外编写路由代码,只需关注业务逻辑的实现。

package main
import (
"flag"
"net/http"
"github.com/zeromicro/go-zero/core/service"
"github.com/zeromicro/go-zero/rest"
)
var port = flag.Int("port", 8888, "server port")
func main() {
flag.Parse()
s := rest.MustNewServer(rest.RestConf{
Port: *port,
})
defer s.Stop()
// 这里通常会调用 handler 注册路由
// 例如:RegisterHandlers(s, ...)
// Swagger 路由已自动注册
// GET /swagger/json -> 返回 JSON 文档
// GET /swagger/web -> 返回 HTML 页面
fmt.Printf("Starting server at %s:%d\n", "0.0.0.0", *port)
s.Start()
}
启动服务后,访问 http://localhost:8888/swagger/web 即可看到 Swagger UI 界面。如果希望自定义 Swagger 信息(如标题、版本),可以在 .api 文件的头部添加全局注释,或者在生成的代码中手动修改顶部的 @title 等注解。
Swagger 文档中如何处理自定义响应结构
当接口返回的结构体包含非标准类型或需要特殊说明时,Swagger 文档可能无法准确展示其含义。此时需要在 .api 文件中为结构体字段添加详细的注释,并确保生成的代码保留了这些注释。对于复杂的嵌套结构,建议在 API 定义中明确每个字段的类型和约束,以便 Swagger 能够正确解析并生成对应的 JSON Schema。


















