Quarkus: Swagger-ui "Try it out" feature ignores root-path defined in Quarkus properties

[troosan]

Describe the bug
In the application.properties I have specified a custom "quarkus.http.root-path"
However, when using swagger-ui, the "Try it out" fires the request without this root-path

Expected behavior
Request is executed against the correct URL

Actual behavior
Request is missing the root-path in the URL

To Reproduce
Steps to reproduce the behavior:

1. go to http://localhost:8080/custom-root/swagger-ui/
2. "Try out" any of your operations

Configuration

quarkus.http.root-path=/custom-root

Environment (please complete the following information):

• Quarkus version: 1.2-Final

[troosan]

found a way around it.
If you define the following in the openapi yml file, the correct path is used.

servers:
  - url: /custom-root

Still, the default auto-generated yml file should also work

[gsmet]

/cc @EricWittmann would it make sense to have a way to push that information to SmallRye OpenAPI?

[EricWittmann]

Yeah I think that if there is a custom root path setting in Quarkus, then that should be pushed into SmallRye OpenAPI so that the generated OAI document is correct.

[machi1990]

found a way around it.
If you define the following in the openapi yml file, the correct path is used.

servers:
  - url: /custom-root

Still, the default auto-generated yml file should also work

I gave it a go here https://github.com/machi1990/quarkus/commit/02f2ad5f9416bf353a7aa9e5fdfddaaf393f7440 but seems like the TCK is broken. Is this the way to go? @EricWittmann

[EricWittmann]

I think ultimately the logic for pushing the custom root path into the OpenAPI document may be a bit more complex than what you have in that commit, @machi1990 but I think that's the spirit. Can you describe how the TCK fails? I'd have to think a little bit on all the implications of doing this - but certainly the TCK isn't designed to be run against a custom context root. I'm just not sure what the consequence of doing that might be...off the top of my head. So I would need to know more about the failure.

The reason I think the logic of adding the custom root path to the OpenAPI document is more complicated, is that there might already be one or more Server defined in the OpenAPI document. So adding another one due to the custom context-path may not always be correct. It's possible to use OpenAPI annotations, and it's also possible to include a static OpenAPI file in the app that contains one or more Server. What would that mean for this use-case?

[machi1990]

I think ultimately the logic for pushing the custom root path into the OpenAPI document may be a bit more complex than what you have in that commit, @machi1990 but I think that's the spirit.

@EricWittmann Thank you for checking my initial commit.

Can you describe how the TCK fails? I'd have to think a little bit on all the implications of doing this - but certainly the TCK isn't designed to be run against a custom context root. I'm just not sure what the consequence of doing that might be...off the top of my head. So I would need to know more about the failure.

The TCK were failing to something you already described:

The reason I think the logic of adding the custom root path to the OpenAPI document is more complicated, is that there might already be one or more Server defined in the OpenAPI document.

What would that mean for this use-case?

I was leaning toward documenting the behaviour (asking users to set servers.url) if root path is set. Not sure what others think?

/cc @gsmet @troosan

[troosan]

Personally, I find using the servers.url is kind of a hack. I works but I don't think that's the intended use.
Of course it's better than nothing ...

[EricWittmann]

Why do you find it a hack? You think the context-path should be part of each path item?

[troosan]

Why do you find it a hack? You think the context-path should be part of each path item?

I checked the documentation a bit (https://swagger.io/docs/specification/api-host-and-base-path/).
And indeed, it seems it is not a hack and can be used to specify a relative path (https://swagger.io/docs/specification/api-host-and-base-path/#relative-urls)

[MawsFr]

Hello @troosan

Do you still have the problem ?

I didn't manage to reproduce your problem when starting from a new project

I followed these steps (including ones from your description) and for me it works :

• Execute :

$ mvn io.quarkus:quarkus-maven-plugin:1.3.0.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=openapi-swaggerui-quickstart-1.2 \
    -DclassName="org.acme.openapi.swaggerui.FruitResource" \
    -Dpath="/fruits" \
    -Dextensions="resteasy-jsonb"

• Execute :

$ ./mvnw quarkus:add-extension -Dextensions="openapi"

• Set quarkus-plugin.version and quarkus.platform.version to 1.2.0-Final

• Execute :

mvn install

• Set quarkus.http.root-path=custom-root in application.properties and put FruitResource, FruitResourceTest and Fruit classes from this url in the project

• Launch the app with mvn compile quarkus:dev

• The step 4 makes the app crash with the error (with what you provided):

java.lang.IllegalArgumentException: Path must start with /

• Put a / before custom-root in application.properties like this quarkus.http.root-path=/custom-root
• Go to http://localhost:8080/custom-root/swagger-ui/
• Try out the 'post' path with a new Fruit
  
  

Seems to work, did I misunderstood something ?

➜ mvn -version
Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
Maven home: /Users/maws/.sdkman/candidates/maven/current
Java version: 13.0.1, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk-13.0.1.jdk/Contents/Home
Default locale: fr_FR, platform encoding: UTF-8
OS name: "mac os x", version: "10.14.6", arch: "x86_64", family: "mac"
➜ java -version
java version "13.0.1" 2019-10-15
Java(TM) SE Runtime Environment (build 13.0.1+9)
Java HotSpot(TM) 64-Bit Server VM (build 13.0.1+9, mixed mode, sharing)

[troosan]

@MawsFr indeed, you are right, the quarkus.http.root-path should start with a /
When I put a / behind /custom-root, I get redirected to http://localhost:8080/custom-root//swagger-ui/ (notice the double / in the url, which makes the request fail). I guess you meant "in front" instead of "behind"

Strangely, when I reproduce your step, it works. It must be the combination with another module/configuration that makes it fail. I'll have to debug more to find what it is.

[MawsFr]

@troosan Yeah sorry for my English I meant 'before', like this : quarkus.http.root-path=/custom-root so by putting a / in front of custom-root, i updated my comment thanks

Strangely, when I reproduce your step, it works. It must be the combination with another module/configuration that makes it fail. I'll have to debug more to find what it is.

Does it still fail by putting the slash in your own project ?

[troosan]

I had the slash in my project, without it it obviously does not work. I'm trying to add the different modules to the test project to see when it will start to fail.

[troosan]

Ok, found it already. Actually in my project I have the following, which makes it fail

package org.acme.openapi.swaggerui;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/v1")
public class RestApplication extends Application {
}

[MawsFr]

Indeed it will work better without @ApplicationPath 😄

[troosan]

Indeed it will work better without @ApplicationPath 😄

Sure, but application is fine with it, so swagger-II should too. But this might definitely help pinpoint the problem.

[MawsFr]

Oh I didn't know that if you set both quarkus.http.root-path=/custom-root and @ApplicationPath("/v1") the final root-path would be custom-root/v1/

The manner you used to set servers.url is not a hack, as you pointed with the documentation, it's the equivalent to the use of @OpenAPIDefinition or @Server (or @Servers combined with @Server)

Example :

import org.eclipse.microprofile.openapi.annotations.servers.Server;
import org.eclipse.microprofile.openapi.annotations.servers.Servers;

@Servers( value = {
        @Server(url = "http://localhost:8080/custom-root" ), 
        @Server(url = "http://server1/custom-root" ),
        @Server(url = "http://server2/custom-root" )}
)
@ApplicationPath( "/v1" )
public class FruitApp extends Application { }

With quarkus.http.root-path=/custom-root set :

[phillip-kruger]

I am looking at this. Am I correct in saying that when using Quarkus without @ApplicationPath in a class that extends javax.ws.rs.core.Application (that is a Quarkus specific feature that allows this), everything works fine (with and without the root-path specified in the config). However, when adding the @ApplicationPath, it only works without the root-path?

@troosan correct ?

[troosan]

That’s right

[phillip-kruger]

Ok I am on it.