Gin框架与Apifox

第一部分：技术栈概述

1. Go语言简介

Go（又称Golang）是Google开发的一门静态类型、编译型编程语言，具有以下特点：

• 高性能：编译为机器码，执行效率接近C/C++

• 简洁语法：没有复杂的OOP概念，学习曲线平缓

• 原生并发：goroutine和channel实现高效并发

• 强大标准库：内置HTTP、JSON、加密等常用功能

• 跨平台：可编译为Windows、Linux、macOS等平台的可执行文件

2. Gin框架介绍

Gin是一个用Go编写的高性能HTTP Web框架：

• 极速路由：基于httprouter，路由匹配速度极快

• 中间件支持：方便扩展认证、日志等功能

• JSON友好：内置高效JSON处理

• 适合API开发：轻量级设计，专注于HTTP服务

3. 开发工具链

• VSCode：轻量级代码编辑器，配合Go插件提供智能提示

• Apifox：API调试工具，可替代Postman，支持：

  • 接口测试

  • 文档生成

  • Mock数据

  • 团队协作

第二部分：项目构建

1.创建项目

mkdir gin-api-demo
cd gin-api-demo
go mod init gin-api-demo 
//是一个 Go 语言的模块初始化命令，用于创建一个新的 Go 模块（module）。这个命令会生成一个 go.mod 文件，该文件用于管理项目的依赖关系。

go get -u github.com/gin-gonic/gin 
//用于下载并安装 Gin 框架，-u 表示 "update"（更新）,如果当前目录有 go.mod 文件，会自动添加 Gin 作为依赖项，并记录版本号,同时生成/更新 go.sum 文件，记录依赖包的哈希校验值（确保安全性）

go mod tidy
//Go 模块（module）管理中的一个重要命令，用于整理和优化项目的依赖关系
//添加缺失的依赖，移除未使用的依赖，同步依赖版本

2.创建main.go文件

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	// 定义路由
	r.GET("/", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"message": "Hello, Gin!",
		})
	})

	// 启动服务器（默认 8080 端口）
	r.Run()
}

3.运行

go run main.go

浏览器访问 http://localhost:8080

第三部分：用户管理API

1.定义用户结构体

在 main.go 中添加：

type User struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Age  int    `json:"age"`
}

var users = []User{
	{ID: "1", Name: "张三", Age: 20},
	{ID: "2", Name: "李四", Age: 25},
}

2.获取所有用户（GET/users）

r.GET("/users", func(c *gin.Context) {
	c.JSON(http.StatusOK, users)
})

3.创建用户（POST/users）

r.POST("/users", func(c *gin.Context) {
	var newUser User
	if err := c.ShouldBindJSON(&newUser); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	users = append(users, newUser)
	c.JSON(http.StatusCreated, newUser)
})

4.获取单个用户（GET /users/:id）

r.GET("/users/:id", func(c *gin.Context) {
	id := c.Param("id")
	for _, user := range users {
		if user.ID == id {
			c.JSON(http.StatusOK, user)
			return
		}
	}
	c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})
})

5.完整代码

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

type User struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	Age  int    `json:"age"`
}

var users = []User{
	{ID: "1", Name: "张三", Age: 20},
	{ID: "2", Name: "李四", Age: 25},
}

func main() {
	r := gin.Default()

	r.GET("/", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"message": "Hello, Gin!",
		})
	})

	r.GET("/users", func(c *gin.Context) {
		c.JSON(http.StatusOK, users)
	})

	r.POST("/users", func(c *gin.Context) {
		var newUser User
		if err := c.ShouldBindJSON(&newUser); err != nil {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}
		users = append(users, newUser)
		c.JSON(http.StatusCreated, newUser)
	})

	r.GET("/users/:id", func(c *gin.Context) {
		id := c.Param("id")
		for _, user := range users {
			if user.ID == id {
				c.JSON(http.StatusOK, user)
				return
			}
		}
		c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})
	})

	r.Run()
}

第四部分：使用 Apifox 测试 API

1.启动服务

go run main.go

2.在 Apifox 中测试

1. 新建项目 → 新建接口

2. 测试 GET /users

   • 方法: GET

   • URL: http://localhost:8080/users

   • 点击 发送，应该返回用户列表

3.测试 POST /users

• 方法: POST

• URL: http://localhost:8080/users

• Body (JSON):

{
  "id": "3",
  "name": "王五",
  "age": 30
}

• 点击 发送，应该返回创建的用户

可以看到状态码响应不对，可以进行修改

4.测试 GET /users/：id

• 方法: GET

• URL: http://localhost:8080/users/1

• 点击 发送，应该返回 ID 为 1 的用户

第五部分：生成Swagger 文档导入 Apifox

1.安装 Swagger 工具

//安装 swag 命令行工具
go install github.com/swaggo/swag/cmd/swag@latest
//验证安装
swag --version  # 应输出版本号（如 v1.16.3）
//安装 Gin 的 Swagger 依赖
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

2.为代码添加 Swagger 注释

(1) 在 main.go 顶部添加全局注释
// @title          用户管理 API（Swagger 版）
// @version        1.0
// @description    这是一个使用 Gin 和 Swagger 实现的用户管理 API
// @host      localhost:8080
// @BasePath  /
func main() {
    r := gin.Default()
    // ...（原有代码）
}

(2) 为每个路由添加注释
示例 1：GET /users（获取所有用户）
// GetUsers 获取所有用户
// @Summary      获取用户列表
// @Description  返回所有用户数据
// @Tags         users
// @Accept       json
// @Produce      json
// @Success      200  {array}   User
// @Router       /users [get]
func GetUsers(c *gin.Context) {
    c.JSON(http.StatusOK, users)
}
示例 2：POST /users（创建用户）
// CreateUser 创建用户
// @Summary      创建新用户
// @Description  接收 JSON 数据并创建用户
// @Tags         users
// @Accept       json
// @Produce      json
// @Param        user  body      User  true  "用户信息"
// @Success      201  {object}  User
// @Failure      400  {object}  map[string]string
// @Router       /users [post]
func CreateUser(c *gin.Context) {
    var newUser User
    if err := c.ShouldBindJSON(&newUser); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    users = append(users, newUser)
    c.JSON(http.StatusCreated, newUser)
}
示例 3：GET /users/:id（获取单个用户）
// GetUserByID 获取单个用户
// @Summary      根据ID获取用户
// @Description  返回指定ID的用户数据
// @Tags         users
// @Accept       json
// @Produce      json
// @Param        id   path      string  true  "用户ID"
// @Success      200  {object}  User
// @Failure      404  {object}  map[string]string
// @Router       /users/{id} [get]
func GetUserByID(c *gin.Context) {
    id := c.Param("id")
    for _, user := range users {
        if user.ID == id {
            c.JSON(http.StatusOK, user)
            return
        }
    }
    c.JSON(http.StatusNotFound, gin.H{"error": "User not found"})
}

3.生成 Swagger 文档

//(1) 运行 swag init
swag init
//生成文件：
docs/
├── docs.go       # Go 代码
├── swagger.json  # Swagger 文档（JSON 格式）
└── swagger.yaml  # Swagger 文档（YAML 格式）

//(2) 导入 docs 包到 main.go
import (
    swaggerFiles "github.com/swaggo/files"     // Swagger UI 静态文件
    ginSwagger "github.com/swaggo/gin-swagger" // Gin 的 Swagger 中间件
    _ "github.com/gin-api-demo/docs"替换为你的模块名（和 go.mod 一致）
    // ...其他导入
)

//(3)打开项目根目录的 go.mod 文件，第一行应类似：
module github.com/你的用户名/gin-api-demo  （没有用户名就不写）


//(4) 添加 Swagger UI 路由
func main() {
    r := gin.Default()
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    // ...（其他路由）
    r.Run()
}

//最后来一下go mod tidy   养成好习惯

4.运行并访问 Swagger UI

//(1) 启动服务器
go run main.go
//(2) 访问 Swagger UI
http://localhost:8080/swagger/index.html

 5.导入 Swagger 到 Apifox

(1) 导出 swagger.json

文件路径：docs/swagger.json。

(2) 在 Apifox 中导入

1. 打开 Apifox → 项目 → 导入 → 选择 swagger.json。

2. 点击 确定，Apifox 会自动解析所有接口。

(3) 在 Apifox 中测试

• 查看自动生成的接口文档。

• 直接发送请求测试（无需手动配置参数）。

总结：swagger文档和apifox搭配可以更加方便导入项目的接口。