第一部分：技术栈概述

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 mainimport ("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 Userif 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 mainimport ("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 Userif 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 中测试

新建项目 → 新建接口
测试 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 Userif 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 中导入

打开 Apifox → 项目 → 导入 → 选择 swagger.json。
点击确定，Apifox 会自动解析所有接口。

(3) 在 Apifox 中测试

查看自动生成的接口文档。
直接发送请求测试（无需手动配置参数）。