如何更改文档呈现的 url 格式？

Question

以下代码：

import (

    "github.com/go-openapi/runtime/middleware"
    "github.com/gorilla/mux"
)

m := mux.NewRouter()

// handlers for API
getRouter := m.Methods(http.MethodGet).Subrouter()
getRouter.HandleFunc("/v1/items", someHandler.ListAll)

// handler for documentation
opts := middleware.RedocOpts{SpecURL: "/swagger.yaml"}
sh := middleware.Redoc(opts, nil)

getRouter.Handle("/docs", sh)
getRouter.Handle("/swagger.yaml", http.FileServer(http.Dir("./")))

---

http://localhost:8080/docs & http://localhost:8080/swagger.yaml 呈现文档。 Api 处理程序也适用于 uri /v1/items

要为http://localhost:8080/v1/docs 和http://localhost:8080/v1/swagger.yaml 呈现文档，以下是所做的更改：

m := mux.NewRouter()

// handlers for API
getRouter := m.Methods(http.MethodGet).PathPrefix("/v1").Subrouter()
getRouter.HandleFunc("/items", someHandler.ListAll)

// handler for documentation
opts := middleware.RedocOpts{SpecURL: "/swagger.yaml",BasePath: "/v1"}
sh := middleware.Redoc(opts, nil)

getRouter.Handle("/docs", sh)
getRouter.Handle("/swagger.yaml", http.FileServer(http.Dir("./")))

但不起作用。 api 处理程序和文档处理程序都失败了

如何在http://localhost:8080/v1/docs 和http://localhost:8080/v1/swagger.yaml 上呈现文档？

如何在http://localhost:8080/v1/items 上渲染 api？随着路径前缀的变化

Answer 1

你快到了。你只需要：

• 从路径中删除 /v1 前缀
• 将BasePath 选项添加到middleware.RedocOpts（参见source on github）
• 在getRouter 定义中添加PathPrefix 方法：

    // handlers for API
    getRouter := m.Methods(http.MethodGet).PathPrefix("/v1").Subrouter()

    // handler for documentation
    opts := middleware.RedocOpts{SpecURL: "/swagger.yaml", BasePath: "/v1"}
    sh := middleware.Redoc(opts, nil)

    getRouter.Handle("/docs", sh)
    getRouter.Handle("/swagger.yaml", http.FileServer(http.Dir("./")))

来自文档：

    // BasePath for the UI path, defaults to: /
    BasePath string
    // Path combines with BasePath for the full UI path, defaults to: docs
    Path string

完整示例：https://play.golang.org/p/U4A60KQ0lD8

Answer 2

查看 middleware.Redoc 方法和关联的模板，SpecURL 选项是直接使用的，没有以 BasePath 为前缀。

为 /swagger.yaml 添加处理程序似乎可行。

type Items struct {}

type Item struct {
    Name string `json:"name"`
}

func (Items) ServeHTTP(w http.ResponseWriter, _ *http.Request) {
    w.WriteHeader(http.StatusOK)
    encoder := json.NewEncoder(w)
    items := []Item{{"Hello"}, {"All"}}
    _ = encoder.Encode(items)
}

func main() {
    m := mux.NewRouter()

    v1routes := m.Methods(http.MethodGet).PathPrefix("/v1").Subrouter()

    opts := middleware.RedocOpts{SpecURL: "/swagger.yaml", BasePath: "/v1"}
    sh := middleware.Redoc(opts, nil)

    v1routes.Handle("/docs", sh)
    // Assumes that the swagger file is in the current working directory and not ./v1/swagger.yaml
    v1routes.Handle("/swagger.yaml", http.StripPrefix("/v1/", http.FileServer(http.Dir("./"))))

    err := http.ListenAndServe(":8000", m)

    fmt.Println(err)
}

http.FileServer 需要匹配的路径。因此，swagger 文件要么需要位于 ./v1 文件夹中，要么需要删除 /v1 前缀。

Answer 3

我忘记更新之前共享的代码中的 SpecUrl。以下对我有用。您需要在当前工作目录中有一个 swagger.yaml 文件。

func main() {
    m := mux.NewRouter()

    v1routes := m.Methods(http.MethodGet).PathPrefix("/v1").Subrouter()

    opts := middleware.RedocOpts{SpecURL: "/v1/swagger.yaml", BasePath: "/v1"}
    sh := middleware.Redoc(opts, nil)

    v1routes.Handle("/docs", sh)
    // Assumes that the swagger file is in the current working directory and not ./v1/swagger.yaml
    v1routes.Handle("/swagger.yaml", http.StripPrefix("/v1/", http.FileServer(http.Dir("./"))))

    err := http.ListenAndServe(":8000", m)

    fmt.Println(err)
}