swagger-maven-plugin w/convertToOpenAPI31 sets dialect rejected by the swagger ui

[shawnsmith]

If you configure the swagger-maven-plugin as follows:

<plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin-jakarta</artifactId>
    <configuration>
        <convertToOpenAPI31>true</convertToOpenAPI31>
        ...
    </configuration>
</plugin>

Then the generated openapi.yaml will contain the following due to https://github.com/swagger-api/swagger-core/blob/v2.2.22/modules/swagger-core/src/main/java/io/swagger/v3/core/util/OpenAPI30To31.java#L13:

jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema

Unfortunately this causes the Swagger UI to display an unfriendly warning due to swagger-api/swagger-ui#8491. The UI expects this instead:

jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base

One possible workaround would be to use the openapi31 config setting instead, which skips setting jsonSchemaDialect:

<plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin-jakarta</artifactId>
    <configuration>
        <openapi31>true</openapi31>
        ...
    </configuration>
</plugin>

but then the generated openapi.yaml will be missing top-level type: object fields in the component schemas because the generator calls schema.type("object") instead of schema.types(Set.of("object")) and skips OpenAPI31SpecFilter/OpenAPISchema2JsonSchema.

[micryc]

@shawnsmith
Fixed by: #4729
Just to mention, the openapi31 flag is the best and correct way to resolve into an OpenAPI 3.1 specification, as it understands 3.1 annotations and correctly uses 3.1 model. convertToOpenAPI31 is an early option to get out a 3.1 doc, still usable but less "powerful"
I would suggest to use openapi31 flag, as issue with missing type: object is already fixed also
I am closing this ticket for now, if there will be still any issues, feel free to reopen