Add url form encoder & decoder (#283)

bfrearson · benfrearson · czechboy0 · web-flow · commit 904e84775a70 · 2023-09-25T11:58:13.000+02:00
### 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 <ben.frearson@sonin.agency> Co-authored-by: bfrearson <> Co-authored-by: Honza Dvorsky <honza@apple.com>
diff --git a/Package.swift b/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"),
diff --git a/Sources/_OpenAPIGeneratorCore/FeatureFlags.swift b/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.
diff --git a/Sources/_OpenAPIGeneratorCore/Translator/CommonTypes/Constants.swift b/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.
diff --git a/Sources/_OpenAPIGeneratorCore/Translator/Content/CodingStrategy.swift b/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
         }
     }
 }
diff --git a/Sources/_OpenAPIGeneratorCore/Translator/Content/ContentInspector.swift b/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,
diff --git a/Sources/_OpenAPIGeneratorCore/Translator/Content/ContentType.swift b/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 {
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Articles/Supported-OpenAPI-features.md b/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
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Development/Converting-between-data-and-Swift-types.md b/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 |
diff --git a/Tests/OpenAPIGeneratorCoreTests/Translator/Content/Test_ContentType.swift b/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",
                     "",
diff --git a/Tests/OpenAPIGeneratorReferenceTests/FileBasedReferenceTests.swift b/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
+            ]
         )
     }
 
diff --git a/Tests/OpenAPIGeneratorReferenceTests/Resources/Docs/petstore.yaml b/Tests/OpenAPIGeneratorReferenceTests/Resources/Docs/petstore.yaml
@@ -113,6 +113,25 @@ paths:
                 $ref: '#/components/schemas/Pet'
         '4XX':
           $ref: '#/components/responses/ErrorBadRequest'
+  /pets/create:
+    summary: Work with pets
+    description: "Create a pet with a URL form"
+    post:
+      summary: Create a pet using a url form
+      operationId: createPetWithForm
+      tags:
+        - pets
+      parameters:
+      requestBody:
+        required: true
+        description: "Create a pet with these properties"
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/CreatePetRequest'
+      responses:
+        '204':
+          description: Successfully created pet using a url form
   /pets/stats:
     get:
       operationId: getStats
diff --git a/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore/Client.swift b/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore/Client.swift
@@ -213,6 +213,37 @@ public struct Client: APIProtocol {
             }
         )
     }
+    /// Create a pet using a url form
+    ///
+    /// - Remark: HTTP `POST /pets/create`.
+    /// - Remark: Generated from `#/paths//pets/create/post(createPetWithForm)`.
+    public func createPetWithForm(_ input: Operations.createPetWithForm.Input) async throws
+        -> Operations.createPetWithForm.Output
+    {
+        try await client.send(
+            input: input,
+            forOperation: Operations.createPetWithForm.id,
+            serializer: { input in let path = try converter.renderedPath(template: "/pets/create", parameters: [])
+                var request: OpenAPIRuntime.Request = .init(path: path, method: .post)
+                suppressMutabilityWarning(&request)
+                switch input.body {
+                case let .urlEncodedForm(value):
+                    request.body = try converter.setRequiredRequestBodyAsURLEncodedForm(
+                        value,
+                        headerFields: &request.headerFields,
+                        contentType: "application/x-www-form-urlencoded"
+                    )
+                }
+                return request
+            },
+            deserializer: { response in
+                switch response.statusCode {
+                case 204: return .noContent(.init())
+                default: return .undocumented(statusCode: response.statusCode, .init())
+                }
+            }
+        )
+    }
     /// - Remark: HTTP `GET /pets/stats`.
     /// - Remark: Generated from `#/paths//pets/stats/get(getStats)`.
     public func getStats(_ input: Operations.getStats.Input) async throws -> Operations.getStats.Output {
diff --git a/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore/Server.swift b/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore/Server.swift
@@ -41,6 +41,12 @@ extension APIProtocol {
             path: server.apiPathComponentsWithServerPrefix(["pets"]),
             queryItemNames: []
         )
+        try transport.register(
+            { try await server.createPetWithForm(request: $0, metadata: $1) },
+            method: .post,
+            path: server.apiPathComponentsWithServerPrefix(["pets", "create"]),
+            queryItemNames: []
+        )
         try transport.register(
             { try await server.getStats(request: $0, metadata: $1) },
             method: .get,
@@ -251,6 +257,47 @@ fileprivate extension UniversalServer where APIHandler: APIProtocol {
             }
         )
     }
+    /// Create a pet using a url form
+    ///
+    /// - Remark: HTTP `POST /pets/create`.
+    /// - Remark: Generated from `#/paths//pets/create/post(createPetWithForm)`.
+    func createPetWithForm(request: Request, metadata: ServerRequestMetadata) async throws -> Response {
+        try await handle(
+            request: request,
+            with: metadata,
+            forOperation: Operations.createPetWithForm.id,
+            using: { APIHandler.createPetWithForm($0) },
+            deserializer: { request, metadata in
+                let contentType = converter.extractContentTypeIfPresent(in: request.headerFields)
+                let body: Operations.createPetWithForm.Input.Body
+                if try contentType == nil
+                    || converter.isMatchingContentType(
+                        received: contentType,
+                        expectedRaw: "application/x-www-form-urlencoded"
+                    )
+                {
+                    body = try converter.getRequiredRequestBodyAsURLEncodedForm(
+                        Components.Schemas.CreatePetRequest.self,
+                        from: request.body,
+                        transforming: { value in .urlEncodedForm(value) }
+                    )
+                } else {
+                    throw converter.makeUnexpectedContentTypeError(contentType: contentType)
+                }
+                return Operations.createPetWithForm.Input(body: body)
+            },
+            serializer: { output, request in
+                switch output {
+                case let .noContent(value):
+                    suppressUnusedWarning(value)
+                    var response = Response(statusCode: 204)
+                    suppressMutabilityWarning(&response)
+                    return response
+                case let .undocumented(statusCode, _): return .init(statusCode: statusCode)
+                }
+            }
+        )
+    }
     /// - Remark: HTTP `GET /pets/stats`.
     /// - Remark: Generated from `#/paths//pets/stats/get(getStats)`.
     func getStats(request: Request, metadata: ServerRequestMetadata) async throws -> Response {
diff --git a/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore/Types.swift b/Tests/OpenAPIGeneratorReferenceTests/Resources/ReferenceSources/Petstore/Types.swift
@@ -24,6 +24,12 @@ public protocol APIProtocol: Sendable {
     /// - Remark: HTTP `POST /pets`.
     /// - Remark: Generated from `#/paths//pets/post(createPet)`.
     func createPet(_ input: Operations.createPet.Input) async throws -> Operations.createPet.Output
+    /// Create a pet using a url form
+    ///
+    /// - Remark: HTTP `POST /pets/create`.
+    /// - Remark: Generated from `#/paths//pets/create/post(createPetWithForm)`.
+    func createPetWithForm(_ input: Operations.createPetWithForm.Input) async throws
+        -> Operations.createPetWithForm.Output
     /// - Remark: HTTP `GET /pets/stats`.
     /// - Remark: Generated from `#/paths//pets/stats/get(getStats)`.
     func getStats(_ input: Operations.getStats.Input) async throws -> Operations.getStats.Output
@@ -1014,6 +1020,42 @@ public enum Operations {
             public static var allCases: [Self] { [.json] }
         }
     }
+    /// Create a pet using a url form
+    ///
+    /// - Remark: HTTP `POST /pets/create`.
+    /// - Remark: Generated from `#/paths//pets/create/post(createPetWithForm)`.
+    public enum createPetWithForm {
+        public static let id: String = "createPetWithForm"
+        public struct Input: Sendable, Hashable {
+            /// - Remark: Generated from `#/paths/pets/create/POST/requestBody`.
+            @frozen public enum Body: Sendable, Hashable {
+                /// - Remark: Generated from `#/paths/pets/create/POST/requestBody/content/application\/x-www-form-urlencoded`.
+                case urlEncodedForm(Components.Schemas.CreatePetRequest)
+            }
+            public var body: Operations.createPetWithForm.Input.Body
+            /// Creates a new `Input`.
+            ///
+            /// - Parameters:
+            ///   - body:
+            public init(body: Operations.createPetWithForm.Input.Body) { self.body = body }
+        }
+        @frozen public enum Output: Sendable, Hashable {
+            public struct NoContent: Sendable, Hashable {
+                /// Creates a new `NoContent`.
+                public init() {}
+            }
+            /// Successfully created pet using a url form
+            ///
+            /// - Remark: Generated from `#/paths//pets/create/post(createPetWithForm)/responses/204`.
+            ///
+            /// HTTP response code: `204 noContent`.
+            case noContent(Operations.createPetWithForm.Output.NoContent)
+            /// Undocumented response.
+            ///
+            /// A response with a code that is not documented in the OpenAPI document.
+            case undocumented(statusCode: Int, OpenAPIRuntime.UndocumentedPayload)
+        }
+    }
     /// - Remark: HTTP `GET /pets/stats`.
     /// - Remark: Generated from `#/paths//pets/stats/get(getStats)`.
     public enum getStats {
diff --git a/Tests/OpenAPIGeneratorReferenceTests/SnippetBasedReferenceTests.swift b/Tests/OpenAPIGeneratorReferenceTests/SnippetBasedReferenceTests.swift
diff --git a/Tests/PetstoreConsumerTests/TestClient.swift b/Tests/PetstoreConsumerTests/TestClient.swift
diff --git a/Tests/PetstoreConsumerTests/TestServer.swift b/Tests/PetstoreConsumerTests/TestServer.swift
diff --git a/Tests/PetstoreConsumerTests/Test_Client.swift b/Tests/PetstoreConsumerTests/Test_Client.swift
diff --git a/Tests/PetstoreConsumerTests/Test_Server.swift b/Tests/PetstoreConsumerTests/Test_Server.swift

Original file line number	Diff line number	Diff line change
`@@ -374,6 +374,9 @@ enum Constants {`
`374`	`374`
`375`	`375`	`/// The substring used in method names for the binary coding strategy.`
`376`	`376`	`static let binary: String = "Binary"`
	`377`	`+`
	`378`	`+ /// The substring used in method names for the url encoded form coding strategy.`
	`379`	`+ static let urlEncodedForm: String = "URLEncodedForm"`
`377`	`380`	`}`
`378`	`381`
`379`	`382`	`/// Constants related to types used in many components.`
Original file line number	Diff line number	Diff line change
`@@ -27,6 +27,9 @@ enum CodingStrategy: String, Hashable, Sendable {`
`27`	`27`	`/// A strategy that passes through the data unmodified.`
`28`	`28`	`case binary`
`29`	`29`
	`30`	`+ /// A strategy using x-www-form-urlencoded.`
	`31`	`+ case urlEncodedForm`
	`32`	`+`
`30`	`33`	`/// The name of the coding strategy in the runtime library.`
`31`	`34`	`var runtimeName: String {`
`32`	`35`	`switch self {`
`@@ -38,6 +41,8 @@ enum CodingStrategy: String, Hashable, Sendable {`
`38`	`41`	`return Constants.CodingStrategy.string`
`39`	`42`	`case .binary:`
`40`	`43`	`return Constants.CodingStrategy.binary`
	`44`	`+ case .urlEncodedForm:`
	`45`	`+ return Constants.CodingStrategy.urlEncodedForm`
`41`	`46`	`}`
`42`	`47`	`}`
`43`	`48`	`}`
Original file line number	Diff line number	Diff line change
`@@ -61,7 +61,7 @@ final class Test_ContentType: Test_Core {`
`61`	`61`	`),`
`62`	`62`	`(`
`63`	`63`	`"application/x-www-form-urlencoded",`
`64`		`- .binary,`
	`64`	`+ .urlEncodedForm,`
`65`	`65`	`"application",`
`66`	`66`	`"x-www-form-urlencoded",`
`67`	`67`	`"",`
Original file line number	Diff line number	Diff line change
`@@ -46,7 +46,10 @@ class FileBasedReferenceTests: XCTestCase {`
`46`	`46`
`47`	`47`	`func testPetstore() throws {`
`48`	`48`	`try _test(`
`49`		`- referenceProject: .init(name: .petstore)`
	`49`	`+ referenceProject: .init(name: .petstore),`
	`50`	`+ featureFlags: [`
	`51`	`+ .urlEncodedForm`
	`52`	`+ ]`
`50`	`53`	`)`
`51`	`54`	`}`
`52`	`55`