quarkus-smallrye-openapi generates unused schemas

[turing85]

Describe the bug

In some cases, quarkus-smallrye-openapi generates schemas that are unused.

Expected behavior

Pre-defined schemas should be used.

Actual behavior

A schema is automagically created, but not used anywhere.

How to Reproduce?

Reproducer:

1. clone https://github.com/turing85/quarkus-openapi-bug:

https://github.com/turing85/quarkus-openapi-bug.git && cd quarkus-openapi-bug

2. Notice that all schemas are defined in OpenApiDefinition.java, line 36 ff. (github.com)
3. Start the application in dev mode

./mvnw clean quarkus:dev

4. Download the schema definition from http://localhost:8080/q/openapi.yml and inspect it:

---
openapi: 3.1.0
info:
  title: quarkus-openapi-bug
  version: 999-SNAPSHOT
components:
  parameters:
    Accept-Encoding:
      in: header
      name: Accept-Encoding
      schema:
        type: string
        enum:
        - gzip
        - deflate
  requestBodies:
    User Request:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User Request"
      required: true
  responses:
    User Response:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User Response"
  schemas:
    User Request: <1>
      type: object
      properties:
        name:
          type: string
    User Response:
      type: object
      properties:
        name:
          type: string
    UserRequest: <2>
      type: object
      properties:
        name:
          type: string
tags:
- name: Users
paths:
  /users:
    post:
      tags:
      - Users
      parameters:
      - $ref: "#/components/parameters/Accept-Encoding"
      requestBody:
        $ref: "#/components/requestBodies/User Request"
      responses:
        "200":
          description: OK
          $ref: "#/components/responses/User Response"
      summary: Post

<1> is the expicitly defined request
<2> is the automagically created request that is not used anywhere

5. Remove the @Parameter-annotation from UserEndpoint.java, line 18 (github.com)

Subject: [PATCH] Remove Parameter annotation from UserEndpoint
---
Index: src/main/java/quarkus/openapi/bug/UserEndpoint.java
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/src/main/java/quarkus/openapi/bug/UserEndpoint.java b/src/main/java/quarkus/openapi/bug/UserEndpoint.java
--- a/src/main/java/quarkus/openapi/bug/UserEndpoint.java	(revision 34168613474e8845c317b1398dc80b40bca31e32)
+++ b/src/main/java/quarkus/openapi/bug/UserEndpoint.java	(date 1735834074199)
@@ -2,11 +2,9 @@

 import jakarta.ws.rs.POST;
 import jakarta.ws.rs.Path;
-import jakarta.ws.rs.core.HttpHeaders;
 import jakarta.ws.rs.core.Response;

 import io.smallrye.mutiny.Uni;
-import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
 import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
@@ -15,7 +13,6 @@
 @Tag(name = "Users")
 public class UserEndpoint {
   @POST
-  @Parameter(ref = HttpHeaders.ACCEPT_ENCODING)
   @APIResponse(ref = OpenApiDefinition.RESPONSE_USER, responseCode = "200")
   public Uni<Response> post(
       @RequestBody(ref = OpenApiDefinition.REQUEST_USER) UserRequest request) {

6. If, necessary restart quarkus in dev-mode
7. Re-download the schema definition from http://localhost:8080/q/openapi.yml and inspect it:

---
openapi: 3.1.0
info:
  title: quarkus-openapi-bug
  version: 999-SNAPSHOT
components:
  parameters:
    Accept-Encoding:
      in: header
      name: Accept-Encoding
      schema:
        type: string
        enum:
        - gzip
        - deflate
  requestBodies:
    User Request:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User Request"
      required: true
  responses:
    User Response:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/User Response"
  schemas:
    User Request:
      type: object
      properties:
        name:
          type: string
    User Response:
      type: object
      properties:
        name:
          type: string
tags:
- name: Users
paths:
  /users:
    post:
      tags:
      - Users
      requestBody:
        $ref: "#/components/requestBodies/User Request"
      responses:
        "200":
          description: OK
          $ref: "#/components/responses/User Response"
      summary: Post

8. Notice that the unused schema is gone

Output of uname -a or ver

Linux xxx 6.8.0-51-generic #52-Ubuntu SMP PREEMPT_DYNAMIC Thu Dec 5 13:09:44 UTC 2024 x86_64 x86_64 x86_64 GNU/Linux

Output of java -version

Openjdk version "21.0.3" 2024-04-16 LTS
OpenJDK Runtime Environment Temurin-21.0.3+9 (build 21.0.3+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.3+9 (build 21.0.3+9-LTS, mixed mode, sharing)

Quarkus version or git rev

3.17.5

Build tool (ie. output of mvnw --version or gradlew --version)

Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: /home/marco/.m2/wrapper/dists/apache-maven-3.9.9/3477a4f1
Java version: 21.0.3, vendor: Eclipse Adoptium, runtime: /opt/java/mandrel/23.1.3.1-java21
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "6.8.0-51-generic", arch: "amd64", family: "unix"

Additional information

No response

[quarkus-bot]

/cc @EricWittmann (openapi), @Karm (mandrel), @Ladicek (smallrye), @MikeEdgar (openapi), @galderz (mandrel), @jmartisk (smallrye), @phillip-kruger (openapi,smallrye), @radcortez (smallrye), @zakkak (mandrel)

[MikeEdgar]

@turing85 the bug/issue here is that the @Parameter(ref = HttpHeaders.ACCEPT_ENCODING) is (incorrectly) being linked to the request body method parameter, generating the schema in the process. Before a fix is available, you should be able to modify the method arguments, adding @Parameter(ref = HttpHeaders.ACCEPT_ENCODING) String acceptEncoding as a work-around.

Alternatively, you can use mp.openapi.extensions.smallrye.remove-unused-schemas.enable=true to drop the unused schema.