Go语言开发Azure Functions集成swagger规范本地运行返回404问题

AI 小北

2026-10-3

排查及解决步骤

第一步：验证swagger文件生成与路径配置
首先确认你已经执行了swag init命令在项目根目录生成了docs文件夹及内部的swagger.json、swagger.yaml等文件。
你当前Swagger函数使用相对路径"docs/swagger.json"读取文件，需要确认运行二进制时的工作目录和docs文件夹处于同一层级。Azure Function本地运行时默认工作目录为项目根目录，若出现路径偏移可以改用go embed将静态文件嵌入二进制，避免路径依赖，示例代码如下：
```
import "embed"
import "net/http"

//go:embed docs/swagger.json
var swaggerJson []byte

func Swagger(c *gin.Context) {
    c.Data(http.StatusOK, "application/json", swaggerJson)
}
```
第二步：修正swagger UI的拉取地址配置
你当前硬编码了swagger json的拉取地址为http://localhost:7071/api/docs，如果本地Azure Function运行端口不是7071，swagger UI会拉取不到配置文件返回404。建议改为相对路径，适配不同运行环境：
```
// 替换原有url配置行
url := ginSwagger.URL("/api/docs")
```
可先单独访问http://<你的运行地址>/api/docs确认可以正常返回swagger json内容，再访问/api/swagger查看UI。

第三步：检查Azure Function自定义处理程序配置
确认项目根目录的host.json中自定义处理程序配置开启了请求转发，且路由前缀和gin路由匹配，示例配置如下：

{
  "version": "2.0",
  "extensions": {
    "http": {
      "routePrefix": "api"
    }
  },
  "customHandler": {
    "description": {
      "defaultExecutablePath": "<你的二进制文件名>",
      "workingDirectory": ".",
      "arguments": []
    },
    "enableForwardingHttpRequest": true
  }
}