Spring open api parameter object

Spring support mapping query params to object via binding for quite a lot.

Recent version of springdoc-openapi starting support of open api documentation on query parameter objects via @Parameter annotation

Simple case

data class RequiredQuery(
    @field:Parameter(required = true)
    val requiredParam: String
)

@GetMapping("required")
fun required(@ParameterObject query: RequiredQuery) = 
    query.requiredParam

Here we use 2 base annotations

• @Parameter from io.swagger.v3.oas.annotations package for field open api description
• @ParameterObject from io.swagger.v3.oas.annotations package for TODO

Following settings will generate:

{
    "openapi": "3.0.1",
    "info": {
        "title": "OpenAPI definition",
        "version": "v0"
    },
    "servers": [
        {
            "url": "http://localhost:8080",
            "description": "Generated server url"
        }
    ],
    "paths": {
        "/required": {
            "get": {
                "tags": [
                    "simple-controller"
                ],
                "operationId": "required",
                "parameters": [
                    {
                        "name": "requiredParam",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "*/*": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {}
}

Multi query object

data class MultipleQuery(
    val u1: String,
    @field:Parameter(required = false)
    val u2: String?,
    @field:Parameter(required = false)
    val u3: String?,
    @field:Parameter(required = false)
    @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)
    val date: LocalDate?
)

Will generate following parameters

"parameters": [
    {
        "name": "u1",
        "in": "query",
        "required": false,
        "schema": {
            "type": "string"
        }
    },
    {
        "name": "u2",
        "in": "query",
        "required": false,
        "schema": {
            "type": "string"
        }
    },
    {
        "name": "u3",
        "in": "query",
        "required": false,
        "schema": {
            "type": "string"
        }
    },
    {
        "name": "date",
        "in": "query",
        "required": false,
        "schema": {
            "type": "string",
            "format": "date"
        }
    }
],