当提供支持多个 API 规范的预生成链接时，Swagger UI 不会加载规范

Question

我有一个用 Go 编写的服务，它也使用 Go 模板作为前端。我们的外部第三方使用此服务作为查找资料和搜索的门户。还有一个服务是 rest API 用于处理订单。门户服务有一个页面，您可以在其中查找 API 文档。我只有一个 API 版本，我使用 SwaggerUI 来显示 API 文档。我必须创建一个新端点并使其成为新 API 版本的一部分。现在我想展示一个新的 API 版本，但也想展示旧版本以支持老客户。是这样的：

因此当用户点击门户网站上的按钮查看文档时，请求由门户中的此功能处理（注意：我已经重构此功能以支持多个 url）：

func getDocs(c echo.Context) error {
    source := c.Get(auth.SourceName).(string)
    key := c.Get(auth.KeyName).(string)

    jsonURLs := []DocsURL{
        {
            url:         fmt.Sprintf("%s/0.1/docs?source=%s", config.baseURL, key),
            name:        "0.1"
        },
        {
            url:         fmt.Sprintf("%s/1.0/docs?source=%s", config.baseURL, key),
            name:        "0.1"
        },
    }

    return c.Render(http.StatusOK, "docs/index", map[string]interface{}{
        "source":   source,
        "key":      key,
        "pageType": "docs",
        "jsonURLs": jsonURLs,
    })
}

这是我使用 SwaggerUI 的模板中的脚本：

  window.onload = function() {
    const ui = SwaggerUIBundle({
      urls: {{ .jsonURLs }},
      dom_id: '#swagger-ui',
      deepLinking: true,
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      plugins: [
        SwaggerUIBundle.plugins.DownloadUrl
      ],
      layout: "StandaloneLayout",
      supportedSubmitMethods: []
    })
    window.ui = ui
    $('.tryitout').prop('disabled', true);
  }

我需要根据环境（生产、暂存、本地）生成链接。在后端生成数据并将其提供给模板进行显示也是有意义的。但这行不通！

但是，如果我对 SwaggerUIBundle 中的链接进行硬编码，它会工作并且门户显示正确的下拉菜单并允许在版本之间切换并加载相应版本的文档。

func getDocs(c echo.Context) error {
    source := c.Get(auth.SourceName).(string)
    key := c.Get(auth.KeyName).(string)

    return c.Render(http.StatusOK, "docs/index", map[string]interface{}{
        "source":   source,
        "key":      key,
        "pageType": "docs",
    })
}

在模板中：

window.onload = function() {
    const ui = SwaggerUIBundle({
      urls: [
        {
          url: "http://localhost:8088/0.1/docs?source=111111",
          name: "0.1"
        },
        {
          url: "http://localhost:8088/1.0/docs?source=111111",
          name: "1.0"
        }
      ],
      dom_id: '#swagger-ui',
      deepLinking: true,
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      plugins: [
        SwaggerUIBundle.plugins.DownloadUrl
      ],
      layout: "StandaloneLayout",
      supportedSubmitMethods: []
    })
    window.ui = ui
    $('.tryitout').prop('disabled', true);
  }

这是为什么？有没有办法让第一个版本的代码工作？

我需要链接是动态的，最好在处理程序中生成。谢谢！

Answer 1

似乎有两个错误：

第一个：

  urls: {{ .jsonURLs }},

这不会为您以 JSON 格式编写 jsonURLs。它会简单地写一个 jsonURLs 的字符串表示。要么你需要编写模板来迭代 jsonURLs 的元素并将它们一一打印出来，要么自己将 jsonURLs 编组为 json：

jsonText,_:=json.Marshal(jsonURLs)
return c.Render(http.StatusOK, "docs/index", map[string]interface{}{
        "source":   source,
        "key":      key,
        "pageType": "docs",
        "jsonURLs": string(jsonText),
    })

其次：您似乎没有导出 DocsURL 结构的成员字段。将字段名称大写并添加 json 标签。

type DocsURL struct {
  URL string `json:"url"`
  Name string `json:"name"`
}

当提供支持多个 API 规范的预生成链接时，Swagger UI 不会加载规范

When providing pregenerated links for supporting multiple API specs Swagger UI doesn't load the specs

api

go

api-doc

go-templates

swagger-ui