一键生成 API 文档：go-zero + Swagger 实践指南

mrkong

在 API 开发中，清晰、准确的接口文档是前后端协作的基石。作为一款强大的 Go 微服务框架，go-zero 提供了便捷的方式自动生成 Swagger 文档，大幅提升了开发效率与接口质量。

本文将详细介绍 Swagger 的作用，以及如何通过 goctl 工具在 go-zero 中一键生成标准的 Swagger 文档。

一、什么是 Swagger？

Swagger 是一套流行的开源 API 文档工具和规范（现为 OpenAPI 规范的前身），能够帮助开发者设计、构建、文档化和测试 RESTful API。它提供了交互式文档、自动化代码生成和清晰的接口描述。

Swagger 的优势：

• 标准统一：结构化 API 描述，便于理解与协作
• 可交互：自带 UI 页面，支持在线测试 API
• 代码生成：支持自动生成客户端/服务端代码
• 版本管理：便于 API 的维护与迭代
• 降本增效：前后端基于统一文档协同开发
  
  

二、go-zero 中如何支持 Swagger？

在 go-zero 中，官方通过 goctl 工具支持 Swagger 文档自动生成。只需要编写好 .api 文件并配置相关信息，即可一键生成符合规范的 Swagger 文档（JSON 或 YAML 格式）。

当前支持说明：

• 需要 goctl 版本 >= 1.8.2（master 分支）
• 需开启实验功能：
  
  

1. goctl env -w GOCTL_EXPERIMENTAL=on
   

复制代码

三、如何在 API 文件中配置 Swagger 信息

go-zero 使用自定义 .api 文件来定义接口。你可以在 info 中配置 Swagger 所需的元信息，如下：

1. syntax = "v1"
   
2. 
   
3. info (
   
4.     title:          "演示 API"
   
5.     description:    "用于生成 Swagger 文档的完整示例"
   
6.     version:        "v1"
   
7.     termsOfService: "https://github.com/zeromicro/go-zero"
   
8.     contactName:    "Kevin"
   
9.     contactEmail:   "example@gmail.com"
   
10.     licenseName:    "MIT"
    
11.     licenseURL:     "https://opensource.org/licenses/MIT"
    
12.     host:           "api.example.com"
    
13.     basePath:       "/v1"
    
14.     wrapCodeMsg:    "true"
    
15. )
    

复制代码

四、如何定义数据结构与请求参数

go-zero 支持通过结构体字段标签来添加参数验证和 Swagger 元信息：

1. type (
   
2.     QueryReq {
   
3.         Id     int    `form:"id,range=[1:10000],example=10"`
   
4.         Name   string `form:"name,example=Kevin"`
   
5.         Avatar string `form:"avatar,optional,example=https://example.com/avatar.png"`
   
6.     }
   
7. 
   
8.     QueryResp {
   
9.         Id   int    `json:"id,example=10"`
   
10.         Name string `json:"name,example=Kevin"`
    
11.     }
    
12. )
    

复制代码

五、接口分组与说明注解

可以通过 @server 标签对接口进行逻辑分组，在 Swagger UI 中将显示为一个 API 分类模块：

1. @server (
   
2.     tags:    "查询接口"
   
3.     summary: "包含各种查询请求"
   
4. )
   
5. 
   
6. service Swagger {
   
7.     @doc (
   
8.         description: "根据参数查询用户"
   
9.     )
   
10.     @handler query
    
11.     get /query (QueryReq) returns (QueryResp)
    
12. 
    
13.     @doc (
    
14.         description: "根据路径参数查询"
    
15.     )
    
16.     @handler queryPath
    
17.     get /query/:id (PathQueryReq) returns (PathQueryResp)
    
18. }
    

复制代码

六、使用 goctl 生成 Swagger 文档
命令示例：

1. goctl api swagger --api example.api --dir ./docs/swagger

复制代码

参数说明：

• --api：API 文件路径
• --dir：生成的 Swagger 文档输出目录
  
  

生成的文档为 swagger.json 文件，可用于集成 Swagger UI。

七、实际案例：复杂 JSON 请求体

1. type (
   
2.     JsonReq {
   
3.         Id       int    `json:"id,range=[1:10000],example=10"`
   
4.         Name     string `json:"name,example=Kevin"`
   
5.         Language string `json:"language,options=golang|java|python"`
   
6.         Gender   string `json:"gender,default=male,options=male|female"`
   
7.     }
   
8. 
   
9.     JsonResp {
   
10.         Id       int    `json:"id"`
    
11.         Name     string `json:"name"`
    
12.         Language string `json:"language"`
    
13.         Gender   string `json:"gender"`
    
14.     }
    
15. )
    
16. 
    
17. @server (
    
18.     tags:    "JSON 请求"
    
19.     summary: "用于演示复杂 JSON 请求体"
    
20. )
    
21. 
    
22. service Swagger {
    
23.     @doc (
    
24.         description: "提交复杂 JSON 请求体"
    
25.     )
    
26.     @handler jsonHandler
    
27.     post /json/simple (JsonReq) returns (JsonResp)
    
28. }
    

复制代码

八、最佳实践建议

为了更好地使用 go-zero 的 Swagger 功能，推荐遵循以下实践：

• ✅ 完善接口信息：填写 title、description、example 等描述字段
• ✅ 清晰结构化：用 @server 进行接口分组
• ✅ 版本管理：始终注明 API 的 version
• ✅ 自动集成：将 goctl api swagger 脚本加入 CI/CD 流程
• ✅ 合理校验：通过标签对请求参数进行验证，提高接口健壮性
  
  

九、总结

go-zero 通过 goctl 提供了对 Swagger 的良好支持，即使该功能仍处于实验阶段，但实际使用中已足够稳定可靠。

只需三步，即可拥有标准化 API 文档：

• 编写 .api 文件并配置 info 元信息
• 开启实验功能并执行生成命令
• 集成 Swagger UI 或前端开发流程
  
  

在微服务架构日益流行的今天，良好的 API 文档体系，是系统可维护性与开发效率的重要保障。go-zero + Swagger 的组合，正是构建现代高质量 API 服务的利器。