swagger-maven-plugin-jakarta generates list of types for all parameters when enabling openAPI31

[ahmed-abdelmonem]

Hello,

I'm using swagger annotations and swager maven plugin to generate our openapi 3.1 specification file. The issue I'm facing is the extra array for parameter types which causes an issue when trying to call the endpoints from the swagger UI.

For example:

@Operation(summary = "Get a list of books",
             responses = { @ApiResponse(responseCode = HttpStatus.SC_OK_STR,
                                        description = HttpResponse.SC_OK), //
                           @ApiResponse(responseCode = HttpStatus.SC_BAD_REQUEST_STR,
                                        description = HttpResponse.SC_BAD_REQUEST) //
             })
  public Response getBooks(@Parameter( required = true, name = "id", schema = @Schema(type = "string")) @PathParam("id") String id) 

will generate:

"/books/{id}" : {
      "get" : {
        "operationId" : "getBooks",
        "parameters" : [ {
          "in" : "path",
          "name" : "id",
          "required" : true,
          "schema" : {
            "type" : [ "string" ]
          }
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "items" : {
                    "type" : [ "string" ]
                  }
                }
              }
            },
            "description" : "Successful Operation"
          },
          "400" : {
            "description" : "Bad Request"
          }
        },
        "summary" : "Get a list of books",
      }
    }

We are using the generated spec file with the latest version of Swagger UI (5.17.10). The issue happens when trying to execute any endpoint with parameters with error "Required field is not provided" even if the field is provided.

[frantuma]

Thanks for reporting this.

How are you serializing the OpenAPI result to JSON? using the maven plugin? Probably the issue comes from not using Yaml31 class for (de)serialization

If the issue persist, please provide the full config to be able to reproduce the issue

[ahmed-abdelmonem]

Thanks for your reply.

I'm serializing the OpenAPI result to JSON using the maven plugin with the below config

<plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin-jakarta</artifactId>
    <executions>
        <execution>
            <id>test</id>
            <phase>compile</phase>
            <goals>
                <goal>resolve</goal>
            </goals>
            <configuration>
                <contextId>test</contextId>
                <outputFileName>swagger</outputFileName>
                <outputPath>${project.build.directory}/classes</outputPath>
                <outputFormat>JSON</outputFormat>
                <configurationFilePath>${basedir}/src/main/resources/swagger/configurationFile.json</configurationFilePath>
            </configuration>
        </execution>
    </executions>
</plugin>

and config file

{
  "resourcePackages": [
    "com.test.rest"
  ],
  "prettyPrint" : true,
  "sortOutput" : true,
  "openAPI31" : true,
  "openAPI": {
    "info": {
      "version": "1.0",
      "title": "Test API",
      "description": "Test API."
    },
    "servers": [
      {
        "url": "$BASE-PATH$"
      }
    ]
  }
}

[frantuma]

This is indeed a bug occurring when setting sortOutput to true. It has been fixed in #4677, and will be available in next release.

Said that, the result is actually still correct in terms of compliance with OpenAPI 3.1, and semantically equal to having type value as string instead of array of strings with single value.

This is also supported by Swagger UI (for OAS 3.1), not sure why you're: which causes an issue when trying to call the endpoints from the swagger UI.

With current version removing the sortOutput property will result in a single value in type

[ahmed-abdelmonem]

@frantuma Thank you for fixing the issue. I meant that having the type as an array of strings caused an error when executing the endpints from the Swagger UI.

I have tested again after setting the sortOutput to false and it looks good in the UI but the APIs are not sorted as expected which should be fixed in the next release.