SwaggerHttp4s does not work with relative paths, only absolutes

[kdrakon]

As per the documented use:

  * Usage: add `new SwaggerHttp4s(yaml).routes[F]` to your http4s router. For example:
  * `Router("/docs" -> new SwaggerHttp4s(yaml).routes[IO])`.
  *
  * When using a custom `contextPath` is used, replace `/docs` with that value.

The problem I've encountered with this is when you go to the redirect path, /docs in this case, the url query parameter is an absolute path to /docs/docs.yaml:

Uri.fromString(s"/$contextPath/index.html?url=/$contextPath/$yamlName")

At my work, we have our application deployed in a kubernetes infrastructure where the REST-based microservices are put under URI namespaces. For example, locally, I could reach my documentation at http://localhost:8000/docs, but in production it would be https://example.com/my-service/docs. The fixed and absolute path above would mean it would try to load the OpenAPI yaml at https://example.com/docs/docs.yaml, resulting in a 404.

In #318, I've made a suggested change so that the contextPath (normally defaulted to docs) is made relative to the http4s Root, thus addressing my above illustrated problem. Furthermore, it allows for the following routing:

Router("/v1" -> (new MyServiceRoutes[IO] <+> new SwaggerHttp4s(yaml).routes[IO]))

So that your docs can sit at http://localhost:8000/v1/docs. This however means, if you wanted the docs at the root, you'd have to now instead do the following:

Router("/" -> new SwaggerHttp4s(yaml).routes[IO]) // routes to /docs

IMO, this makes more sense, especially since it gives more meaning to the parameter name contextPath.

[kdrakon]

Pull request ready #318

[kdrakon]

Extra note:
To further my point of the issue, this is how I put my docs under a different relative path in version 0.12.2:

Router(
  "/v1" -> new MyServiceRoutes[IO]
  "/v1/doc" -> new SwaggerHttp4s(yaml, contextPath = "v1/doc").routes[IO])
)

Having to correctly state the path like this twice is a code smell.

[adamw]

Released in 0.12.3