convert urlencoded request body to query parameters (openapi-processor/openapi-processor-spring#412)

Author: hauner

openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/converter/ApiConverter.kt

@@ -30,6 +30,7 @@ import io.openapiprocessor.core.model.Response as ModelResponse
 import io.openapiprocessor.core.model.parameters.Parameter as ModelParameter
 
 const val MULTIPART = "multipart/"
+const val URLENCODED = "application/x-www-form-urlencoded"
 const val INTERFACE_DEFAULT_NAME = ""
 
 /**
@@ -236,8 +237,12 @@ class  ApiConverter(
                 mediaType.getSchema(),
                 ctx.resolver)
 
-            if (contentType.startsWith(MULTIPART)) {
+            if (isMultipart(contentType)) {
                 params.addAll(createMultipartParameter(info, mediaType.encodings, ctx.dataTypes))
+
+            } else if (isUrlencoded(contentType)) {
+                params.addAll(createFormParameter(info, ctx.dataTypes))
+
             } else {
                 bodies.add (createRequestBody (contentType, info, requestBody, ctx.dataTypes))
             }
@@ -246,6 +251,10 @@ class  ApiConverter(
         return RequestBodies(bodies, params)
     }
 
+    private fun isMultipart(contentType: String): Boolean = contentType.startsWith(MULTIPART)
+
+    private fun isUrlencoded(contentType: String): Boolean = contentType.startsWith(URLENCODED)
+
     private fun collectResponses(responses: Map<HttpStatus, Response>, ctx: ApiConverterContext): Map<ModelHttpStatus, List<ModelResponse>> {
         val resultResponses: MutableMap<HttpStatus, List<ModelResponse>>  = mutableMapOf()
         val contentTypeInterfaces = collectContentTypeInterfaces(responses, ctx)
@@ -274,7 +283,7 @@ class  ApiConverter(
         // to check if a response marker interface is wanted it is necessary to know if the responses have the same
         // result data type. In case they have the same data type we do not need the marker interface.
         //
-        // Unfortunately we have to calculate the result data types to achieve this because it is currently not possible
+        // Unfortunately, we have to calculate the result data types to achieve this because it is currently not possible
         // to detect this from the parsed OpenAPI.
 
         val checkResponses: MutableMap<ModelHttpStatus, List<ModelResponse>> = mutableMapOf()
@@ -390,8 +399,21 @@ class  ApiConverter(
         val parameters = mutableListOf<ModelParameter>()
         dataType.forEach { property, propertyDataType ->
             val mpp = MultipartParameter(property, encodings[property]?.contentType)
-            val parameter = framework.createMultipartParameter(mpp, propertyDataType)
-            parameters.add(parameter)
+            parameters.add(framework.createMultipartParameter(mpp, propertyDataType))
+        }
+        return parameters
+    }
+
+    private fun createFormParameter(info: SchemaInfo, dataTypes: DataTypes): Collection<ModelParameter> {
+        val dataType = convertDataType(info, dataTypes)
+        if (dataType !is ObjectDataType) {
+            throw NoRequestBodySchemaException(info.getPath())
+        }
+
+        dataTypes.del(dataType)
+        val parameters = mutableListOf<ModelParameter>()
+        dataType.forEach { property, propertyDataType ->
+            parameters.add(framework.createQueryParameter(UrlencodedParameter(property), propertyDataType))
         }
         return parameters
     }

openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/converter/NoRequestBodySchemaException.kt

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 https://github.com/openapi-processor/openapi-processor-core
+ * PDX-License-Identifier: Apache-2.0
+ */
+
+package io.openapiprocessor.core.converter
+
+/**
+ * thrown when the ApiConverter hits a multipart/form-data or application/x-www-form-urlencoded
+ * response body where the schema is not an object.
+ */
+class NoRequestBodySchemaException(private val path: String): RuntimeException() {
+
+    override val message: String
+        get() = "the schema of the request body of $path should be an object!"
+
+}

openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/parser/UrlencodedParameter.kt

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2026 https://github.com/openapi-processor/openapi-processor-core
+ * PDX-License-Identifier: Apache-2.0
+ */
+
+package io.openapiprocessor.core.parser
+
+/**
+ * "fake" parameter for framework-specific annotation selection
+ */
+class UrlencodedParameter(val parameter: String): Parameter {
+
+    override fun getIn(): String {
+        return "urlencoded"
+    }
+
+    override fun getName(): String {
+        return parameter
+    }
+
+    override fun getSchema(): Schema {
+        throw NotImplementedError() // never called
+    }
+
+    override fun isRequired(): Boolean {
+        return true
+    }
+
+    override fun isDeprecated(): Boolean {
+        return false
+    }
+
+    override val description: String?
+        get() = null
+
+}

openapi-processor-core/src/test/kotlin/io/openapiprocessor/core/converter/ApiConverterRequestBodySpec.kt

@@ -266,4 +266,64 @@ class ApiConverterRequestBodySpec: StringSpec({
         dts.find("MultipartPostRequestBodyJson").shouldNotBeNull()
         dts.find("MultipartPostRequestBody").shouldBeNull()
     }
+
+    "converts request body application/x-www-form-urlencoded object schema properties to request parameters" {
+        val openApi = parseApiBody("""
+            paths:
+              /foo:
+                post:
+                  requestBody:
+                    required: true
+                    content:
+                      application/x-www-form-urlencoded:
+                        schema:
+                          type: object
+                          properties:
+                            foo:
+                              type: string
+                            bar:
+                              type: boolean
+                  responses:
+                    '204':
+                      description: empty
+            """)
+
+        val api = apiConverter().convert(openApi)
+
+        val itf = api.getInterfaces().first()
+        val ep = itf.endpoints.first()
+        val foo = ep.parameters[0]
+        val bar = ep.parameters[1]
+
+        foo.dataType.getName() shouldBe "string"
+        foo.dataType.getTypeName() shouldBe "String"
+        foo.name shouldBe "foo"
+
+        bar.dataType.getName() shouldBe "boolean"
+        bar.dataType.getTypeName() shouldBe "Boolean"
+        bar.name shouldBe "bar"
+    }
+
+    "throws when request body application/x-www-form-urlencoded is not an object schema" {
+        val openApi = parseApiBody("""
+            paths:
+              /multipart/broken:
+                post:
+                  requestBody:
+                    required: true
+                    content:
+                      application/x-www-form-urlencoded:
+                        schema:
+                          type: string
+                  responses:
+                    '204':
+                      description: empty
+            """)
+
+        val e = shouldThrow<NoRequestBodySchemaException> {
+            apiConverter(framework = mockk()).convert(openApi)
+        }
+
+        e.message shouldContain "/multipart/broken"
+    }
 })

openapi-processor-core/src/testInt/kotlin/io/openapiprocessor/core/ProcessorTestSets.kt

@@ -52,6 +52,7 @@ val ALL_3x: List<TestParams2> = join(
     testX("params-path-simple-data-types"), // framework specific
     tests("params-request-body"), // framework specific
     testX("params-request-body-multipart-form-data"), // framework specific
+    testX("params-request-body-form-urlencoded"), // framework specific
     testX("params-simple-data-types"), // framework specific
     testX("params-unnecessary"),
     tests("ref-array-items-nested"),

openapi-processor-core/src/testInt/resources/tests/params-request-body-form-urlencoded/inputs.yaml

@@ -0,0 +1,6 @@
+prefix: api
+items:
+  - inputs/openapi30.yaml
+  - inputs/openapi31.yaml
+  - inputs/openapi32.yaml
+  - inputs/mapping.yaml

openapi-processor-core/src/testInt/resources/tests/params-request-body-form-urlencoded/inputs/mapping.yaml

@@ -0,0 +1,5 @@
+openapi-processor-mapping: v16
+
+options:
+  package-name: generated
+  format-code: false

openapi-processor-core/src/testInt/resources/tests/params-request-body-form-urlencoded/inputs/openapi30.yaml

@@ -0,0 +1,22 @@
+openapi: 3.0.2
+info:
+  title: x-form-www-urlencoded
+  version: 1.0.0
+
+paths:
+  /foo:
+    post:
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                foo:
+                  type: string
+                bar:
+                  type: string
+      responses:
+        '204':
+          description: empty

openapi-processor-core/src/testInt/resources/tests/params-request-body-form-urlencoded/inputs/openapi31.yaml

@@ -0,0 +1,22 @@
+openapi: 3.1.0
+info:
+  title: x-form-www-urlencoded
+  version: 1.0.0
+
+paths:
+  /foo:
+    post:
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                foo:
+                  type: string
+                bar:
+                  type: string
+      responses:
+        '204':
+          description: empty

openapi-processor-core/src/testInt/resources/tests/params-request-body-form-urlencoded/inputs/openapi32.yaml

@@ -0,0 +1,22 @@
+openapi: 3.2.0
+info:
+  title: x-form-www-urlencoded
+  version: 1.0.0
+
+paths:
+  /foo:
+    post:
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                foo:
+                  type: string
+                bar:
+                  type: string
+      responses:
+        '204':
+          description: empty