swagger-api / swagger-api/swagger-core

BUG Spec generator should ignore org.glassfish.jersey.media.multipart.MultiPart

Open
#4,661 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backlog
Dominant language
Java
Stars
7.5k
Forks
2.3k
Avg merge
18h 1m
Merged PRs (30d)
10

Description

I have a jaxrs endpoint which has to accept a complicated multipart message using Jersey.
This is the endpoint:

    @POST
    @Consumes("multipart/mixed")
    @Produces("application/json")
    @Path("tool/{id}/pipelineparams")
    @Operation(summary = "Does something",
            requestBody = @RequestBody(content = @Content(schema = @Schema(type = "string", format = "binary"))),
            responses = {
            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = SomeModelClass.class))),
            @ApiResponse(responseCode = "422", description = "Can happen"),
            @ApiResponse(responseCode = "404", description = "Can happen"),
            @ApiResponse(responseCode = "409", description = "Can happen"),
    })
    public Response doSomething(@PathParam("id") String id,  MultiPart multiPart) throws IOException {

The swagger generator plugin will correctly understand that it should treat this endpoint as a "binary" endpoint.
(The other side will have to manually craft the message which I handwrite in the client anyways)

MultiPart is org.glassfish.jersey.media.multipart.MultiPart

For some reason the generator decides to include Model Spec of org.glassfish.jersey.media.multipart.MultiPart.
Due to me overriding the requestBody the Model of MultiPart is not used anywhere but it is still included in the spec. This is not desired as it generates a few very confusing Model Classes in any client generating a client from the spec.

This is one such model that should really not be generated:

      "MultiPart" : {
        "type" : "object",
        "properties" : {
          "bodyParts" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/BodyPart"
            }
          },
          "contentDisposition" : {
            "$ref" : "#/components/schemas/ContentDisposition"
          },
          "entity" : {
            "type" : "object"
          },
          "headers" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "items" : {
                "type" : "string"
              }
            },
            "properties" : {
              "empty" : {
                "type" : "boolean"
              }
            }
          },
          "mediaType" : {
            "$ref" : "#/components/schemas/MediaType"
          },
          "messageBodyWorkers" : {
            "$ref" : "#/components/schemas/MessageBodyWorkers"
          },
          "parameterizedHeaders" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "items" : {
                "$ref" : "#/components/schemas/ParameterizedHeader"
              }
            },
            "properties" : {
              "empty" : {
                "type" : "boolean"
              }
            }
          },
          "parent" : {
            "$ref" : "#/components/schemas/MultiPart"
          },
          "providers" : {
            "$ref" : "#/components/schemas/Providers"
          }
        }
      },

The genrate should completly ignore any "models" in the org.glassfish.jersey.media.multipart and treat them as If they were "InputStream".

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the reported JAX-RS endpoint using org.glassfish.jersey.media.multipart.MultiPart and inspect the spec generator's model handling. Confirm that the overridden binary request body remains unchanged while MultiPart and its related Jersey models are absent from the generated specification.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.