Add url form encoder & decoder (#283)

### Motivation

#182 Currently, the generated interface for request bodies that use
URLEncodedForms accepts a `Data` object. This PR uses the
URIEncoder/Decoder to instead provide an interface using codable types
in the same way that a JSON body would.

### Modifications
Adds a new coding strategy that works with the corresponding [runtime
converter
updates](apple/swift-openapi-runtime#53).

**Note:** This PR does not support encoding collections of primitives
(i.e. an array of string values for a single key). This should be
addressed in a future update, but it raised questions about the correct
use of URIEncoder, so I didn't include it in this PR. Further discussion
of the issue is in the [runtime
PR](apple/swift-openapi-runtime#53).

### Result
Generated interfaces now directly accept URLEncodedForm Codable types
rather than untyped `Data`.

### Test Plan

Updated reference tests to include a request using a form body.

---------

Co-authored-by: benfrearson <[email protected]>
Co-authored-by: bfrearson <>
Co-authored-by: Honza Dvorsky <[email protected]>

Author: 3 people

Package.swift

@@ -89,7 +89,7 @@ let package = Package(
         // Tests-only: Runtime library linked by generated code, and also
         // helps keep the runtime library new enough to work with the generated
         // code.
-        .package(url: "https://github.com/apple/swift-openapi-runtime", .upToNextMinor(from: "0.2.2")),
+        .package(url: "https://github.com/apple/swift-openapi-runtime", .upToNextMinor(from: "0.2.4")),
 
         // Build and preview docs
         .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),

Sources/_OpenAPIGeneratorCore/FeatureFlags.swift

@@ -32,6 +32,10 @@ public enum FeatureFlag: String, Hashable, Codable, CaseIterable, Sendable {
     /// A dedicated field in OpenAPI 3.0, a `null` value present in
     /// the `types` array in OpenAPI 3.1.
     case nullableSchemas
+
+    /// Support for `application/x-www-form-urlencoded` request bodies as
+    /// structured payloads.
+    case urlEncodedForm
 }
 
 /// A set of enabled feature flags.

Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/Constants.swift

@@ -374,6 +374,9 @@ enum Constants {
 
         /// The substring used in method names for the binary coding strategy.
         static let binary: String = "Binary"
+
+        /// The substring used in method names for the url encoded form coding strategy.
+        static let urlEncodedForm: String = "URLEncodedForm"
     }
 
     /// Constants related to types used in many components.

Sources/_OpenAPIGeneratorCore/Translator/Content/CodingStrategy.swift

@@ -27,6 +27,9 @@ enum CodingStrategy: String, Hashable, Sendable {
     /// A strategy that passes through the data unmodified.
     case binary
 
+    /// A strategy using x-www-form-urlencoded.
+    case urlEncodedForm
+
     /// The name of the coding strategy in the runtime library.
     var runtimeName: String {
         switch self {
@@ -38,6 +41,8 @@ enum CodingStrategy: String, Hashable, Sendable {
             return Constants.CodingStrategy.string
         case .binary:
             return Constants.CodingStrategy.binary
+        case .urlEncodedForm:
+            return Constants.CodingStrategy.urlEncodedForm
         }
     }
 }

Sources/_OpenAPIGeneratorCore/Translator/Content/ContentInspector.swift

@@ -247,7 +247,15 @@ extension FileTranslator {
                 schema: .b(.string)
             )
         }
-        if !excludeBinary, contentKey.isBinary {
+        let urlEncodedFormsSupported = config.featureFlags.contains(.urlEncodedForm)
+        if urlEncodedFormsSupported && contentKey.isUrlEncodedForm {
+            let contentType = ContentType(contentKey.typeAndSubtype)
+            return .init(
+                contentType: contentType,
+                schema: contentValue.schema
+            )
+        }
+        if !excludeBinary, contentKey.isBinary || !urlEncodedFormsSupported {
             let contentType = contentKey.asGeneratorContentType
             return .init(
                 contentType: contentType,

Sources/_OpenAPIGeneratorCore/Translator/Content/ContentType.swift

@@ -45,6 +45,16 @@ struct ContentType: Hashable {
         /// either to the network (requests) or to the caller (responses).
         case binary
 
+        /// A content type for x-www-form-urlencoded.
+        ///
+        /// The top level properties of a Codable data model are encoded
+        /// as key-value pairs in the form:
+        ///
+        ///  `key1=value1&key2=value2`
+        ///
+        /// The type is encoded as a binary UTF-8 data packet.
+        case urlEncodedForm
+
         /// Creates a category from the provided type and subtype.
         ///
         /// First checks if the provided content type is a JSON, then text,
@@ -59,6 +69,8 @@ struct ContentType: Hashable {
                 self = .json
             } else if lowercasedType == "text" {
                 self = .text
+            } else if lowercasedType == "application" && lowercasedSubtype == "x-www-form-urlencoded" {
+                self = .urlEncodedForm
             } else {
                 self = .binary
             }
@@ -73,6 +85,8 @@ struct ContentType: Hashable {
                 return .string
             case .binary:
                 return .binary
+            case .urlEncodedForm:
+                return .urlEncodedForm
             }
         }
     }
@@ -236,6 +250,10 @@ struct ContentType: Hashable {
         category == .binary
     }
 
+    var isUrlEncodedForm: Bool {
+        category == .urlEncodedForm
+    }
+
     static func == (lhs: Self, rhs: Self) -> Bool {
         // MIME type equality is case-insensitive.
         lhs.lowercasedTypeAndSubtype == rhs.lowercasedTypeAndSubtype
@@ -254,6 +272,12 @@ extension OpenAPI.ContentType {
         asGeneratorContentType.isJSON
     }
 
+    /// A Boolean value that indicates whether the content type
+    /// is a URL-encoded form.
+    var isUrlEncodedForm: Bool {
+        asGeneratorContentType.isUrlEncodedForm
+    }
+
     /// A Boolean value that indicates whether the content type
     /// is a type of plain text.
     var isText: Bool {

Sources/swift-openapi-generator/Documentation.docc/Articles/Supported-OpenAPI-features.md

@@ -12,6 +12,20 @@ Supported features are always provided on _both_ client and server.
 
 > Tip: If a feature you need isn't currently supported, let us know by filing an issue, or even contribute a pull request. For more information, check out <doc:Contributing-to-Swift-OpenAPI-Generator>.
 
+### Structured content types
+
+For the checked serialization formats below, the generator emits types conforming to `Codable`, structured based on the provided JSON Schema.
+
+For any other formats, the payload is provided as raw bytes, leaving it up to the adopter to decode as needed.
+
+- [x] JSON
+    - when content type is `application/json` or ends with `+json`
+- [x] URL-encoded form request bodies
+    - when content type is `application/x-www-form-urlencoded`
+- [ ] multipart
+    - tracked by [#36](https://github.com/apple/swift-openapi-generator/issues/36)
+- [ ] XML
+
 ### OpenAPI specification features
 
 #### OpenAPI Object

Sources/swift-openapi-generator/Documentation.docc/Development/Converting-between-data-and-Swift-types.md

@@ -53,6 +53,9 @@ Below is a list of the "dimensions" across which the helper methods differ:
     - `URI`
         - example: query, path, header parameters
         - `color=red&power=24`
+    - `urlEncodedForm`
+        - example: request body with the `application/x-www-form-urlencoded` content type
+        - `greeting=Hello+world`
     - `string`
         - example: `text/plain`, and any other `text/*` content type
         - `"red color and power of 24"`
@@ -94,6 +97,8 @@ method parameters: value or type of value
 | client | set | request body | JSON | required | setRequiredRequestBodyAsJSON |
 | client | set | request body | binary | optional | setOptionalRequestBodyAsBinary |
 | client | set | request body | binary | required | setRequiredRequestBodyAsBinary |
+| client | set | request body | urlEncodedForm | optional | setOptionalRequestBodyAsURLEncodedForm | 
+| client | set | request body | urlEncodedForm | required | setRequiredRequestBodyAsURLEncodedForm | 
 | client | get | response body | string | required | getResponseBodyAsString |
 | client | get | response body | JSON | required | getResponseBodyAsJSON |
 | client | get | response body | binary | required | getResponseBodyAsBinary |
@@ -106,6 +111,8 @@ method parameters: value or type of value
 | server | get | request body | JSON | required | getRequiredRequestBodyAsJSON |
 | server | get | request body | binary | optional | getOptionalRequestBodyAsBinary |
 | server | get | request body | binary | required | getRequiredRequestBodyAsBinary |
+| server | get | request body | urlEncodedForm | optional | getOptionalRequestBodyAsURLEncodedForm |
+| server | get | request body | urlEncodedForm | required | getRequiredRequestBodyAsURLEncodedForm |
 | server | set | response body | string | required | setResponseBodyAsString |
 | server | set | response body | JSON | required | setResponseBodyAsJSON |
 | server | set | response body | binary | required | setResponseBodyAsBinary |

Tests/OpenAPIGeneratorCoreTests/Translator/Content/Test_ContentType.swift

@@ -61,7 +61,7 @@ final class Test_ContentType: Test_Core {
                 ),
                 (
                     "application/x-www-form-urlencoded",
-                    .binary,
+                    .urlEncodedForm,
                     "application",
                     "x-www-form-urlencoded",
                     "",

Tests/OpenAPIGeneratorReferenceTests/FileBasedReferenceTests.swift

@@ -46,7 +46,10 @@ class FileBasedReferenceTests: XCTestCase {
 
     func testPetstore() throws {
         try _test(
-            referenceProject: .init(name: .petstore)
+            referenceProject: .init(name: .petstore),
+            featureFlags: [
+                .urlEncodedForm
+            ]
         )
     }