Quarkus: Quarkus exports Openapi json specs without @PathParam parameters

[r00ta]

Describe the bug

The openapi specs downloaded from /openapi contains all the properties, but the json specs downloaded from /openapi.json is different and for example it does not contain the @PathParam parameters.

Expected behavior
Parameters annotated with @PathParam should be included in the specs downloaded from /openapi.json

Actual behavior
Parameters annotated with @PathParam are not included in the specs downloaded from /openapi.json

To Reproduce
Steps to reproduce the behavior:

1. Create a simple project and enable the quarkus openapi extension
2. navigate to /openapi
3. navigate to /openapi.json -> this one does not contain all the info.

Configuration

quarkus.http.port=8180
quarkus.http.test-port=8181
quarkus.http.cors=true
quarkus.swagger-ui.always-include=true

    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-smallrye-openapi</artifactId>
    </dependency>
    <dependency>
      <groupId>io.swagger.core.v3</groupId>
      <artifactId>swagger-jaxrs2</artifactId>
      <version>2.1.1</version>
    </dependency>
    <dependency>
        <groupId>javax.ws.rs</groupId>
        <artifactId>javax.ws.rs-api</artifactId>
        <version>2.1.1</version>
      </dependency>
      <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1.0</version>
      </dependency>
  </dependencies>

Screenshots
I'm using the following endpoint:

@Path("/executions")
public class ExecutionsApi {

    @Inject
    IEventStorage storageService;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public ExecutionResponse getExecutions(@DefaultValue("yesterday") @QueryParam("from") String from,
                                           @DefaultValue("now") @QueryParam("to") String to,
                                           @DefaultValue("100") @QueryParam("limit") int limit,
                                           @DefaultValue("0") @QueryParam("offset") int offset) {

This is what the swagger-ui provides (all good here, 'cause it fetches data from /openapi)

But the specs at /openapi.json returns

... "/executions":{"get":{"operationId":"getExecutions","requestBody":{"content":{"*/*":{"schema":{"type":"string","default":"yesterday"}}}},"responses":{"default":{"description":"default response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionResponse"}}}}}}},"/executions/processes/{key}":{"get":{"operationId":"getExecutionByKey_1","requestBody":{"content":{"*/*":{"schema":{"type":"string"}}}},"responses":{"default":{"description":"default response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionDetailResponse"}}}}}}}

Environment (please complete the following information):

• Output of uname -a or ver:

Linux ubuntu-bionic 4.15.0-91-generic #92-Ubuntu SMP Fri Feb 28 11:09:48 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux
 - Output of `java -version`: openjdk 11.0.6 2020-01-14
OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.6+10)
OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.6+10, mixed mode)

• GraalVM version (if different from Java):
• Quarkus version or git rev: 1.3.1.Final
• Build tool (ie. output of mvnw --version or gradlew --version):

Maven home: /home/vagrant/.m2/wrapper/dists/apache-maven-3.6.2-bin/795eh28tki48bv3l67maojf0ra/apache-maven-3.6.2
Java version: 11.0.6, vendor: AdoptOpenJDK, runtime: /home/vagrant/.jabba/jdk/[email protected]
Default locale: en, platform encoding: UTF-8
OS name: "linux", version: "4.15.0-91-generic", arch: "amd64", family: "unix"

Additional context
No more

[quarkusbot]

/cc @EricWittmann

[geoand]

cc @phillip-kruger

[EricWittmann]

I'll have a look, but it's likely to be some problem in the Quarkus extension. We have pretty extensive tests in SmallRye to make sure that the output is the same regardless of whether it's YAML or JSON formatted.

I have no idea right now how the /openapi and /openapi.json endpoints might differ. But hopefully it won't be hard to figure out. :)

Also note that the MP OpenAPI spec requires the /openapi endpoint - there's nothing in the spec about /openapi.json. The former endpoint can serve both YAML (default) and JSON (via query param or request header). Details here: https://github.com/eclipse/microprofile-open-api/blob/master/spec/src/main/asciidoc/microprofile-openapi-spec.adoc#openapi-endpoint

I'm assuming that /openapi.json is an alias for /openapi with query parameter format set to JSON. But that's just an assumption, and I haven't found that anywhere in the Quarkus code yet.

[EricWittmann]

Question for @r00ta - is there any chance you have an openapi.json file bundled in your application? Perhaps in META-INF for example?

[r00ta]

@EricWittmann Thanks!
Nope, I don't have any openapi.json file in my META-INF. The strange thing is that without the following dependencies

    <dependency>
      <groupId>io.swagger.core.v3</groupId>
      <artifactId>swagger-jaxrs2</artifactId>
      <version>2.1.1</version>
    </dependency>
    <dependency>
        <groupId>javax.ws.rs</groupId>
        <artifactId>javax.ws.rs-api</artifactId>
        <version>2.1.1</version>
      </dependency>
      <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1.0</version>
      </dependency>

The /openapi.json is not available at all! I will create a sample project to reproduce the issue in few hours!

[EricWittmann]

OK a sample app would be good. I don't think the Quarkus OpenAPI extension defines a /openapi.json endpoint - so it's perhaps coming from one of those dependencies. I just created a sample Quarkus app with OpenAPI enabled and I get a 404 for that endpoint.

I'll add those deps and see what I get. :)

[EricWittmann]

You were right, this is the dependency that is adding "support" for /openapi.json:

<dependency>
      <groupId>io.swagger.core.v3</groupId>
      <artifactId>swagger-jaxrs2</artifactId>
      <version>2.1.1</version>
    </dependency>

When I add/remove that it enables/disables the /openapi.json endpoint. In my example case that endpoint just returns an empty OpenAPI document.

So this is now well outside my area of knowledge. :) I don't know why you have that dependency enabled or what it does.

[r00ta]

Maybe it was my misunderstanding but reading the following documentation https://quarkus.io/guides/openapi-swaggerui I was expecting that an export of a json specs was supported by the quarkus-smallrye-openapi addon. Is it correct?
I tried many other packages to export swagger api, but all of them are not exporting properly all the parameters.

[gsmet]

By adding the Swagger jar, you get Swagger to generate the JSON.

What you need to do is either:

• GET /openapi?format=json
• GET /openapi with an Accept header application/json

And you will get the output of the file generated by SmallRye OpenAPI as JSON.

[r00ta]

Thank you very much @gsmet , that works like a charm!