swagger-core

swagger-core copied to clipboard

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 https://github.com/swagger-api/swagger-ui/issues/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.