当前位置：首页 > article >正文

gin集成Swagger

article 2025/1/6 18:36:16

gin集成Swagger

1、首先安装 swag 命令行工具：

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

2、添加 Swagger 相关依赖到项目：

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

3、在 main.go 中添加基础配置：

package main

import (
    _ "xxx-api/docs"  // 这里会引入即将自动生成的 docs 包
)

// @title           xxx API
// @version         1.0
// @description     xxx统 API 服务
// @termsOfService  http://swagger.io/terms/

// @contact.name   API Support
// @contact.url    http://www.swagger.io/support
// @contact.email  support@swagger.io

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html

// @host      localhost:8080
// @BasePath  /api

// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization
func main() {
    // ... 现有代码 ...
}

4、修改 routers/router.go，添加 Swagger 路由：

package routers

import (
    "github.com/gin-gonic/gin"
    swaggerFiles "github.com/swaggo/files"
    ginSwagger "github.com/swaggo/gin-swagger"
)

func InitRouter(engine *gin.Engine) {
    // ... 现有代码 ...

    // Swagger API 文档
    // 仅在开发环境启用
    if gin.Mode() != gin.ReleaseMode {
        engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    }
}

5、创建一个初始化 Swagger 的脚本 scripts/swagger.sh：

#!/bin/bash

# 生成 swagger 文档
swag init

# 如果文档生成成功，打印访问地址
if [ $? -eq 0 ]; then
    echo "Swagger 文档生成成功！"
    echo "请访问: http://localhost:8080/swagger/index.html"
else
    echo "Swagger 文档生成失败！"
fi