Swagger 是围绕 OpenAPI 规范构建的一套 API 工具生态，可以用于 API 设计、文档生成、接口测试和维护。

在 Go 项目中，通常结合 swaggo/swag 和 gin-swagger 自动生成接口文档，方便前后端联调。

环境说明

技术	版本
Go	>= 1.20
Gin	>= 1.9
swaggo/swag	>= 1.8
gin-swagger	最新稳定版本

项目结构

project
├── main.go
├── controller
│   └── user.go
├── model
│   └── response.go
└── docs
    ├── docs.go
    ├── swagger.json
    └── swagger.yaml

Swagger 与 OpenAPI

OpenAPI 是 REST API 描述规范。

Swagger 是围绕 OpenAPI 构建的一套工具生态，包括：

Swagger UI
Swagger Editor
Swagger Codegen

Go 项目流程

Go 注释
    ↓
swag 解析
    ↓
OpenAPI 文档
    ↓
Swagger UI 展示

安装 swag CLI

go install github.com/swaggo/swag/cmd/swag@latest

Bash

检查：

swag --version

Bash

添加 Swagger 基础信息

main.go：

package main

// @title 用户管理系统 API 文档
// @version 1.0
// @description 用户服务接口文档
// @host localhost:8080
// @BasePath /api/v1
// @schemes http https

func main() {

}

JWT 鉴权配置

// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization
// @description 输入 Bearer Token

接口：

// @Security BearerAuth

定义返回模型

推荐使用明确 struct，而不是 interface{}：

package model

type Response struct {
    Code int `json:"code"`
    Msg  string `json:"msg"`
}

type UserResponse struct {
    Code int `json:"code"`
    Msg  string `json:"msg"`
    Data User `json:"data"`
}

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

Controller 添加接口注释

package controller

import (
    "github.com/gin-gonic/gin"

    "project/model"
)

// GetUserInfo
// @Summary 获取用户信息
// @Description 根据用户 ID 查询用户详情
// @Tags 用户模块
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} model.UserResponse
// @Failure 400 {object} model.Response
// @Failure 500 {object} model.Response
// @Router /user/{id} [get]

func GetUserInfo(c *gin.Context) {

    c.JSON(
        200,
        model.UserResponse{
            Code: 200,
            Msg: "success",
            Data: model.User{
                ID: 1,
                Name: "测试用户",
            },
        },
    )
}

生成 Swagger 文档

swag init

Bash

生成：

docs
├── docs.go
├── swagger.json
└── swagger.yaml

注意：docs 目录属于自动生成文件，不建议手动修改。

多目录项目

入口：

cmd/server/main.go

执行：

swag init -g cmd/server/main.go

Bash

依赖解析：

swag init --parseDependency --parseInternal

Bash

集成 gin-swagger

安装：

go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files/v2

Bash

main.go 完整示例：

package main

import (
    "github.com/gin-gonic/gin"

    swaggerFiles "github.com/swaggo/files/v2"
    ginSwagger "github.com/swaggo/gin-swagger"

    _ "project/docs"
)

func main() {

    r := gin.Default()

    r.GET(
        "/swagger/*any",
        ginSwagger.WrapHandler(swaggerFiles.Handler),
    )

    r.Run(":8080")
}

注意：project/docs 需要替换为实际 go.mod 中的 module 名称。

访问 Swagger UI

启动：

go run main.go

Bash

访问：

http://localhost:8080/swagger/index.html

生产环境注意事项

生产环境通常关闭 Swagger：

if gin.Mode() != gin.ReleaseMode {

    r.GET(
        "/swagger/*any",
        ginSwagger.WrapHandler(
            swaggerFiles.Handler,
        ),
    )

}

常见问题

Swagger 页面没有接口：

检查：

swag init

Bash

确认：

import _ "project/docs"

Router：

// @Router /user/{id} [get]

修改接口后文档没有更新：

重新执行：

swag init

Bash

swag init 找不到接口：

检查：

main.go 路径
Controller 是否被扫描
是否执行：

swag init --parseDependency --parseInternal

Bash

CI/CD 自动生成 Swagger

示例：

- name: Generate Swagger
  run: swag init

- name: Check docs
  run: git diff --exit-code

YAML

作用：

避免代码修改后 API 文档不同步。

总结

Go 注释
      ↓
swag init
      ↓
swagger.json
      ↓
gin-swagger
      ↓
Swagger UI

Gin + Swagger 可以快速建立规范化 API 文档。

企业项目建议结合：

JWT 鉴权
API Version
请求响应模型设计
CI/CD 自动生成
文档版本管理

形成完整 API 文档管理体系。

Swagger 是围绕 OpenAPI 规范构建的一套 API 工具生态，可以用于 API 设计、文档生成、接口测试和维护。

在 Go 项目中，通常结合 swaggo/swag 和 gin-swagger 自动生成接口文档，方便前后端联调。

环境说明

技术	版本
Go	>= 1.20
Gin	>= 1.9
swaggo/swag	>= 1.8
gin-swagger	最新稳定版本

项目结构

project
├── main.go
├── controller
│   └── user.go
├── model
│   └── response.go
└── docs
    ├── docs.go
    ├── swagger.json
    └── swagger.yaml

Swagger 与 OpenAPI

OpenAPI 是 REST API 描述规范。

Swagger 是围绕 OpenAPI 构建的一套工具生态，包括：

Swagger UI
Swagger Editor
Swagger Codegen

Go 项目流程

Go 注释
    ↓
swag 解析
    ↓
OpenAPI 文档
    ↓
Swagger UI 展示

安装 swag CLI

go install github.com/swaggo/swag/cmd/swag@latest

Bash

检查：

swag --version

Bash

添加 Swagger 基础信息

main.go：

package main

// @title 用户管理系统 API 文档
// @version 1.0
// @description 用户服务接口文档
// @host localhost:8080
// @BasePath /api/v1
// @schemes http https

func main() {

}

JWT 鉴权配置

// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization
// @description 输入 Bearer Token

接口：

// @Security BearerAuth

定义返回模型

推荐使用明确 struct，而不是 interface{}：

package model

type Response struct {
    Code int `json:"code"`
    Msg  string `json:"msg"`
}

type UserResponse struct {
    Code int `json:"code"`
    Msg  string `json:"msg"`
    Data User `json:"data"`
}

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

Controller 添加接口注释

package controller

import (
    "github.com/gin-gonic/gin"

    "project/model"
)

// GetUserInfo
// @Summary 获取用户信息
// @Description 根据用户 ID 查询用户详情
// @Tags 用户模块
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} model.UserResponse
// @Failure 400 {object} model.Response
// @Failure 500 {object} model.Response
// @Router /user/{id} [get]

func GetUserInfo(c *gin.Context) {

    c.JSON(
        200,
        model.UserResponse{
            Code: 200,
            Msg: "success",
            Data: model.User{
                ID: 1,
                Name: "测试用户",
            },
        },
    )
}

生成 Swagger 文档

swag init

Bash

生成：

docs
├── docs.go
├── swagger.json
└── swagger.yaml

注意：docs 目录属于自动生成文件，不建议手动修改。

多目录项目

入口：

cmd/server/main.go

执行：

swag init -g cmd/server/main.go

Bash

依赖解析：

swag init --parseDependency --parseInternal

Bash

集成 gin-swagger

安装：

go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files/v2

Bash

main.go 完整示例：

package main

import (
    "github.com/gin-gonic/gin"

    swaggerFiles "github.com/swaggo/files/v2"
    ginSwagger "github.com/swaggo/gin-swagger"

    _ "project/docs"
)

func main() {

    r := gin.Default()

    r.GET(
        "/swagger/*any",
        ginSwagger.WrapHandler(swaggerFiles.Handler),
    )

    r.Run(":8080")
}

注意：project/docs 需要替换为实际 go.mod 中的 module 名称。

访问 Swagger UI

启动：

go run main.go

Bash

访问：

http://localhost:8080/swagger/index.html

生产环境注意事项

生产环境通常关闭 Swagger：

if gin.Mode() != gin.ReleaseMode {

    r.GET(
        "/swagger/*any",
        ginSwagger.WrapHandler(
            swaggerFiles.Handler,
        ),
    )

}

常见问题

Swagger 页面没有接口：

检查：

swag init

Bash

确认：

import _ "project/docs"

Router：

// @Router /user/{id} [get]

修改接口后文档没有更新：

重新执行：

swag init

Bash

swag init 找不到接口：

检查：

main.go 路径
Controller 是否被扫描
是否执行：

swag init --parseDependency --parseInternal

Bash

CI/CD 自动生成 Swagger

示例：

- name: Generate Swagger
  run: swag init

- name: Check docs
  run: git diff --exit-code

YAML

作用：

避免代码修改后 API 文档不同步。

总结

Go 注释
      ↓
swag init
      ↓
swagger.json
      ↓
gin-swagger
      ↓
Swagger UI

Gin + Swagger 可以快速建立规范化 API 文档。

企业项目建议结合：

JWT 鉴权
API Version
请求响应模型设计
CI/CD 自动生成
文档版本管理

形成完整 API 文档管理体系。