在Golang Gin API中集成OpenAPI 3.0 YAML与Swagger UI求助

1. 安装必要依赖 #

安装支持OpenAPI 3.0的Swagger工具包，直接执行以下命令：

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

2. 放置OpenAPI 3.0规范文件 #

将你编写好的OpenAPI 3.0 YAML文件（比如命名为openapi.yaml）放在项目根目录的docs文件夹下（路径示例：./docs/openapi.yaml）。以下是一个极简的规范示例供参考：

openapi: 3.0.3
info:
  title: 示例API文档
  version: 1.0.0
paths:
  /api/v1/users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

3. 在Gin中配置Swagger UI路由 #

在你的Gin主入口文件（比如main.go）中，导入依赖并添加Swagger UI的访问路由，同时指定加载你的OpenAPI 3.0文件：

package main

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

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

	// 配置Swagger UI指向你的OpenAPI 3.0文件
	swaggerUrl := ginSwagger.URL("/docs/openapi.yaml")
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, swaggerUrl))

	// 添加静态文件路由，让Swagger UI能读取到OpenAPI文件
	r.Static("/docs", "./docs")

	// 你的业务API路由示例
	r.GET("/api/v1/users", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"data": []gin.H{
				{"id": 1, "name": "张三"},
				{"id": 2, "name": "李四"},
			},
		})
	})

	r.Run(":8080")
}

4. 启动并访问Swagger UI #

运行你的Gin项目：

go run main.go

打开浏览器访问 http://localhost:8080/swagger/index.html，即可看到基于OpenAPI 3.0的可视化文档界面，直接在页面上就能测试API接口。

常见问题排查 #

• 若Swagger UI加载不出YAML文件：检查docs文件夹的路径是否正确，静态路由r.Static("/docs", "./docs")是否配置，确保文件权限正常。
• 若提示OpenAPI格式错误：用Swagger Editor验证你的YAML文件是否符合3.0规范，修正语法或结构问题。

内容的提问来源于stack exchange，提问作者Ajay