升级OpenAPI 3.1后查询参数在生成器与Swagger UI中异常

技术栈 #

<java.version>17</java.version>

<spring.boot.version>3.1.1</spring.boot.version>

<org.springdoc.openapi.version>2.2.0</org.springdoc.openapi.version>

OpenAPI描述 #

"/v1/rente/auskunft/{annr}": {
    "get": {
        "operationId": "rentenAuskunft",
        "parameters": [
            {
                "in": "path",
                "name": "annr",
                "description": "arbeitnehmernummer",
                "required": true,
                "schema": {
                    "type": "integer",
                    "format": "int64"
                }
            },
            {
                "in": "query",
                "style": "deepObject",
                "explode": true,
                "name": "rentenAuskunftParamsDto",
                "required": true,
                "schema": {
                    "$ref": "#/components/schemas/RentenAuskunftParamsDto"
                }
            }
        ]
    }
}

OpenAPI生成器Maven插件配置 #

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.5.0</version>
    <executions>
        <execution>
            <id>rente-api</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <generatorName>spring</generatorName>
                <library>spring-boot</library>
                <skipIfSpecIsUnchanged>true</skipIfSpecIsUnchanged>
                <generateApis>true</generateApis>
                <generateApiDocumentation>true</generateApiDocumentation>
                <generateApiTests>false</generateApiTests>
                <generateModels>true</generateModels>
                <generateModelDocumentation>false</generateModelDocumentation>
                <generateModelTests>false</generateModelTests>
                <generateSupportingFiles>true</generateSupportingFiles>
                <output>${project.build.directory}/generated-sources</output>
                <modelPackage>xxx.model</modelPackage>
                <apiPackage>xxx.api</apiPackage>
                <skipValidateSpec>false</skipValidateSpec>
                <typeMappings>
                    <typeMapping>OffsetDateTime=java.time.LocalDateTime</typeMapping>
                </typeMappings>
                <schemaMappings>
                </schemaMappings>
                <configOptions>
                    <sourceFolder>main/java</sourceFolder>
                    <useSpringBoot3>true</useSpringBoot3>
                    <validateSpec>false</validateSpec>
                    <interfaceOnly>true</interfaceOnly>
                    <!--Use modern java8 date/time api-->
                    <dateLibrary>java8</dateLibrary>
                    <!--Enable bean validation using javax validation and hibernate validator-->
                    <useBeanValidation>true</useBeanValidation>
                    <performBeanValidation>true</performBeanValidation>
                    <openApiNullable>false</openApiNullable>
                    <!--Place required parameters first in models-->
                    <sortModelPropertiesByRequiredFlag>true</sortModelPropertiesByRequiredFlag>
                    <sortParamsByRequiredFlag>true</sortParamsByRequiredFlag>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

生成的API代码 #

@RequestMapping 
(method = RequestMethod.GET,value ="/v1/rente/auskunft/{annr}",
produces = {"application/json"})
default
ResponseEntity<RentenAuskunftResponse>rentenAuskunft(
@Parameter
(name ="annr",description ="arbeitnehmernummer",required =true,in = ParameterIn.PATH)
@PathVariable("annr") Long annr,
@NotNull @Parameter(name ="rentenAuskunftParamsDto",required =true,in = ParameterIn.QUERY)
@Valid
 RentenAuskunftParamsDto rentenAuskunftParamsDto)

问题 #

将OpenAPI版本从3.0.3升级至3.1.0后，Swagger UI无法以对象样式渲染查询参数，配置的deepObject风格未生效，同时nullable配置也不起作用，需要解决这两个问题。

内容的提问来源于stack exchange，提问作者csk