说在前头

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平台。

主要功能

核心功能模块

1. 智能API文档生成

   • 自动识别Gin路由定义和处理函数
   • 支持Swagger/OpenAPI 2.0规范生成
   • 在VS Code侧边栏预览API文档
   • 自动提取路由注释作为API描述

2. API导航与组织

   • API列表视图按文件夹组织
   • 支持API搜索功能
   • 从列表直接跳转到API定义位置
   • 支持批量选择API接口

3. Apifox平台集成

   • 一键上传API文档到Apifox
   • 支持选择性上传指定API
   • 将API保存为OpenAPI规范文件
   • 自动提取结构体用于请求/响应定义

4. 代码智能增强

   • 自动解析Go结构体标签(json/binding等)
   • 从注释中提取示例值
   • 自动识别路径参数、查询参数和请求体
   • 支持嵌套结构体解析

使用方法

1. 安装插件，在插件市场搜索 apifox-for-go-gin
2. 在Go+Gin项目中，使用 Ctrl+Shift+P 输入 apifox-go.uploadApiDocs 上传API文档到Apifox
3. 根据提示输入Apifox的API Key，项目id，项目名称
4. 上传成功后，在Apifox中查看生成的API文档

插件工作原理

1. 解析项目中所有 .go 文件
2. 识别Gin框架的路由定义：r.GET("path", handlerFunc)
3. 提取路由处理函数的参数和返回值
4. 解析参数结构体定义和标签
5. 生成符合OpenAPI规范的文档
6. 通过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"`
}

注意事项

1. 插件目前支持标准的Gin路由定义方式
2. 为获得更好的文档效果，建议在路由和处理函数上添加注释
3. 使用@apiFolder标记可以指定API分组文件夹
4. 确保在结构体定义时使用标准的Go标签格式
5. 项目启动后会自动激活插件

配置选项

插件会在项目根目录下创建 .apifox-go.json 配置文件，存储Apifox的相关配置：

{
  "apiKey": "your-apifox-api-key",
  "projectId": "your-apifox-project-id",
  "projectName": "Gin API Documentation"
}

常见问题

1. 如遇插件无法识别路由，请检查路由定义是否符合标准Gin格式
2. 结构体字段无法正确解析，请确保标签格式正确
3. 路径参数识别问题，确保使用:param格式定义路径参数

未来开发计划

1. 支持更多Gin路由定义方式
2. 完善Mock数据生成功能
3. 添加对Swagger注解的额外支持
4. 实现HTTP请求发送测试功能