Overview Version History Q & A Rating & Review
说在前头
apifox 官方出品的 api 自动生成没有适配 go 语言的,所以这个插件非常适合使用 go 开发的项目,同时还想使用 apifox 的用户。
用法参考哔哩哔哩视频 https://www.bilibili.com/video/BV1T84y1G76W/ 这个视频是 idea 插件的,但是我这个插件是 vscode 的。
借鉴自 VS APIFOX Helper
APIFOX for GO + GIN
这是一个用于Gin+Go项目的VS Code插件,用于自动解析Gin路由并生成API文档,支持一键上传到Apifox平台。
主要功能
核心功能模块
智能API文档生成
自动识别Gin路由定义和处理函数
支持Swagger/OpenAPI 2.0规范生成
在VS Code侧边栏预览API文档
自动提取路由注释作为API描述
API导航与组织
API列表视图按文件夹组织
支持API搜索功能
从列表直接跳转到API定义位置
支持批量选择API接口
Apifox平台集成
一键上传API文档到Apifox
支持选择性上传指定API
将API保存为OpenAPI规范文件
自动提取结构体用于请求/响应定义
代码智能增强
自动解析Go结构体标签(json/binding等)
从注释中提取示例值
自动识别路径参数、查询参数和请求体
支持嵌套结构体解析
使用方法
安装插件,在插件市场搜索 apifox-for-go-gin
在Go+Gin项目中,使用 Ctrl+Shift+P
输入 apifox-go.uploadApiDocs
上传API文档到Apifox
根据提示输入Apifox的API Key,项目id,项目名称
上传成功后,在Apifox中查看生成的API文档
插件工作原理
解析项目中所有 .go
文件
识别Gin框架的路由定义:r.GET("path", handlerFunc)
提取路由处理函数的参数和返回值
解析参数结构体定义和标签
生成符合OpenAPI规范的文档
通过Apifox API上传文档或保存到本地文件
示例路由识别
插件能够识别以下形式的Gin路由定义:
// UserController 用户相关接口
// @apiFolder 用户管理
package controllers
import (
"github.com/gin-gonic/gin"
)
// 初始化路由
func RegisterUserRoutes(r *gin.RouterGroup) {
userGroup := r.Group("/users")
{
// 获取用户列表
userGroup.GET("", ListUsers)
// 获取单个用户信息
userGroup.GET("/:id", GetUser)
// 创建新用户
userGroup.POST("", CreateUser)
// 更新用户信息
userGroup.PUT("/:id", UpdateUser)
// 删除用户
userGroup.DELETE("/:id", DeleteUser)
}
}
// ListUsers 获取用户列表
func ListUsers(c *gin.Context) {
page := c.Query("page")
size := c.Query("size")
// ...处理逻辑
}
// GetUser 获取单个用户
func GetUser(c *gin.Context) {
id := c.Param("id")
// ...处理逻辑
}
// CreateUser 创建用户
func CreateUser(c *gin.Context) {
var user User
if err := c.ShouldBindJSON(&user); err != nil {
// ...错误处理
return
}
// ...处理逻辑
}
// User 用户结构体
type User struct {
ID int64 `json:"id"`
Username string `json:"username" binding:"required"`
Email string `json:"email" binding:"required,email"`
Phone string `json:"phone"`
CreatedAt string `json:"created_at"`
}
注意事项
插件目前支持标准的Gin路由定义方式
为获得更好的文档效果,建议在路由和处理函数上添加注释
使用@apiFolder
标记可以指定API分组文件夹
确保在结构体定义时使用标准的Go标签格式
项目启动后会自动激活插件
配置选项
插件会在项目根目录下创建 .apifox-go.json
配置文件,存储Apifox的相关配置:
{
"apiKey": "your-apifox-api-key",
"projectId": "your-apifox-project-id",
"projectName": "Gin API Documentation"
}
常见问题
如遇插件无法识别路由,请检查路由定义是否符合标准Gin格式
结构体字段无法正确解析,请确保标签格式正确
路径参数识别问题,确保使用:param
格式定义路径参数
未来开发计划
支持更多Gin路由定义方式
完善Mock数据生成功能
添加对Swagger注解的额外支持
实现HTTP请求发送测试功能