Mount example doesn't work. what's the right way to have both v1 and v2 on a server?

[chz8494]

Hey guys,

Very good project for swagger 3.x, really appreciated your work. I'd like to create a server with v1 and v2 server url, so was trying to follow https://github.com/swaggest/rest/blob/master/_examples/mount/main.go example to mount endpoints under api/v1, but has following error with service.Mount("/api/v1", apiV1):

panic: reflect API schema for GET /api/v1/sum: operation already exists: get /api/v1/sum

goroutine 1 [running]:
github.com/swaggest/rest/nethttp.OpenAPIMiddleware.func1({0x1012d9600?, 0x14000373920?})
    /Users/267121010/go/pkg/mod/github.com/swaggest/rest@v0.2.61/nethttp/openapi.go:35 +0x1a8

I also tried to use

r := openapi31.NewReflector()
r.Spec.WithServers(
    openapi31.Server{
        URL: "/api/v1",
    })
s := web.NewService(r)
s.Route("/data", func(r chi.Router) {
    r.Group(func(r chi.Router) {
        r.Use(serviceTokenAuth, serviceTokenDoc, checkSize)
        r.Method(http.MethodPost, "/", nethttp.NewHandler(handler.GenericPost()))
        r.Method(http.MethodPost, "/file-upload", nethttp.NewHandler(handler.FileUploader()))
    })
})
s.Docs(“/docs”, swgui.New)

with this code I can see server url options in the swagger gui, but the actual endpoint logic is not correctly mapped to server selection. I'd expect to be able to call endpoint <url>/api/v1/data, but the server is actually only listening on <url>/data, the swagger GUI call test does show correct curl example <url>/api/v1/data though.

[vearutop]

Thank you for raising this, this example is now fixed in latest master.

[chz8494]

Thank you for the quick update. I've tried it and no more errors. But it still cannot achieve what I want. Your example

apiV1.Post("/sum", sum())
s.Mount("/api/v1", apiV1)

seems providing same function as using

s.Route("/api/v1", func(r chi.Router) {
    r.Group(func(r chi.Router) {
        r.Use(sessMW, sessDoc)

        r.Method(http.MethodGet, "/sum", nethttp.NewHandler(sum()))
    })
})

it just adds pattern /api/v1 in front of whatever defined in apiV1.

what I want to do is to have server version options selectable and make routes mapping correctly in swagger GUI. with your new code, if I add this line in the beginning:

r := openapi3.NewReflector()
r.Spec.WithServers(
  openapi31.Server{
    URL: "/api/v1",
  },
  openapi31.Server{
    URL: "/api/v2",
  }
)
s := web.NewService(r)

and if choose /api/v1, the swagger GUI curl example will call to endpoint localhost/api/v1/api/v1/ instead of localhost/api/v1

[vearutop]

Hi, I think you need both individual spec configuration for each versioned API and Swagger UI setup that allows selection from multiple API specs.

Please check an example https://github.com/swaggest/rest/blob/master/_examples/multi-api/main.go

// Package main implements an example where two versioned API revisions are mounted into root web service
// and are available through a service selector in Swagger UI.
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "net/http"

    "github.com/go-chi/chi/v5/middleware"
    "github.com/swaggest/openapi-go"
    "github.com/swaggest/openapi-go/openapi3"
    "github.com/swaggest/rest/nethttp"
    "github.com/swaggest/rest/web"
    swg "github.com/swaggest/swgui"
    swgui "github.com/swaggest/swgui/v5emb"
    "github.com/swaggest/usecase"
)

func main() {
    fmt.Println("Swagger UI at http://localhost:8010/api/docs.")
    if err := http.ListenAndServe("localhost:8010", service()); err != nil {
        log.Fatal(err)
    }
}

func service() *web.Service {
    // Creating root service, to host versioned APIs.
    s := web.NewService(openapi3.NewReflector())
    s.OpenAPISchema().SetTitle("Security and Mount Example")

    // Each versioned API is exposed with its own OpenAPI schema.
    v1r := openapi3.NewReflector()
    v1r.SpecEns().WithServers(openapi3.Server{URL: "/api/v1/"}).WithInfo(openapi3.Info{Title: "My API of version 1"})
    apiV1 := web.NewService(v1r)

    v2r := openapi3.NewReflector()
    v2r.SpecEns().WithServers(openapi3.Server{URL: "/api/v2/"})
    apiV2 := web.NewService(v2r)

    // Versioned APIs may or may not have their own middlewares and wraps.
    apiV1.Wrap(
        middleware.BasicAuth("Admin Access", map[string]string{"admin": "admin"}),
        nethttp.HTTPBasicSecurityMiddleware(s.OpenAPICollector, "Admin", "Admin access"),
        nethttp.OpenAPIAnnotationsMiddleware(s.OpenAPICollector, func(oc openapi.OperationContext) error {
            oc.SetTags(append(oc.Tags(), "V1")...)
            return nil
        }),
    )
    apiV1.Post("/sum", sum())
    apiV1.Post("/mul", mul())
    // Once all API use cases are added, schema can be served too.
    apiV1.Method(http.MethodGet, "/openapi.json", specHandler(apiV1.OpenAPICollector.SpecSchema()))

    apiV2.Post("/summarization", sum())
    apiV2.Post("/multiplication", mul())
    apiV2.Method(http.MethodGet, "/openapi.json", specHandler(apiV2.OpenAPICollector.SpecSchema()))

    // Prepared versioned API services are mounted with their base URLs into root service.
    s.Mount("/api/v1", apiV1)
    s.Mount("/api/v2", apiV2)

    // Root docs needs a bit of hackery to expose versioned APIs as separate services.
    s.Docs("/api/docs", swgui.NewWithConfig(swg.Config{
        ShowTopBar: true,
        SettingsUI: map[string]string{
            // When "urls" are configured, Swagger UI ignores "url" and switches to multi API mode.
            "urls": `[
    {"url": "/api/v1/openapi.json", "name": "APIv1"}, 
    {"url": "/api/v2/openapi.json", "name": "APIv2"}
]`,
            `"urls.primaryName"`: `"APIv2"`, // Using APIv2 as default.
        },
    }))

    // Blanket handler, for example to serve static content.
    s.Mount("/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        _, _ = w.Write([]byte("blanket handler got a request: " + r.URL.String()))
    }))

    return s
}

func specHandler(s openapi.SpecSchema) http.Handler {
    j, err := json.Marshal(s)
    if err != nil {
        panic(err)
    }

    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        _, _ = w.Write(j)
    })
}

func mul() usecase.Interactor {
    return usecase.NewInteractor(func(ctx context.Context, input []int, output *int) error {
        *output = 1

        for _, v := range input {
            *output *= v
        }

        return nil
    })
}

func sum() usecase.Interactor {
    return usecase.NewInteractor(func(ctx context.Context, input []int, output *int) error {
        for _, v := range input {
            *output += v
        }

        return nil
    })
}

[chz8494]

@vearutop Thank you for the example code update, it does solved most of the problem, I can now use banner to switch json profile and gui reflects endpoint pattern correctly. but this solution seems not work with grouped route auth middleware, e.g:

s.Route("/data", func(r chi.Router) {
    r.Group(func(r chi.Router) {
        r.Use(sessMW, sessDoc)

        r.Method(http.MethodGet, "/sum", nethttp.NewHandler(sum()))
    })
})

the api is functioning correctly and accepting auth, but GUI doesn't have auth options/icon displayed, openapi.json doesn't have security related content either. I also tried with s.With(sessMW, sessDoc), not work either.

and the example code

apiV1.Wrap(
        middleware.BasicAuth("Admin Access", map[string]string{"admin": "admin"}),
        nethttp.HTTPBasicSecurityMiddleware(s.OpenAPICollector, "Admin", "Admin access"),
        nethttp.OpenAPIAnnotationsMiddleware(s.OpenAPICollector, func(oc openapi.OperationContext) error {
            oc.SetTags(append(oc.Tags(), "V1")...)
            return nil
        }),
    )

causes the whole apiV1 page becomes BasicAuth

[chz8494]

Ok, I kind of got it work by

apiV1.Route("/data", func(r chi.Router) {
    r.Group(func(r chi.Router) {
        r.Use(serviceTokenAuth, serviceTokenDoc, checkSize)
        r.Method(http.MethodGet, "/sum", nethttp.NewHandler(sum()))
    })
})
// Swagger GUI to have authorization schema and input
apiV1.OpenAPISchema().SetAPIKeySecurity("apiKey", "Authorization", oapi.InHeader, "API Key.")
// to add authorization schema under route group so that Swagger GUI example curl can call
for _, pi := range v1r.Spec.Paths.MapOfPathItemValues {
  pi.Post.Security = []map[string][]string{
    {
      "apiKey": []string{},
    },
  }
}
apiV1.Method(http.MethodGet, "/docs/openapi.json", specHandler(apiV1.OpenAPICollector.SpecSchema()))

but it's not ideal, I'd prefer apiV1.OpenAPICollector.SpecSchema() to pick up correct security values by itself.