URLQueryEncoder
A customizable Swift Encoder that encodes instances of data types as URL query items. Supports all OpenAPI serialization options.
Examples
Encoding Primitives
let encoder = URLQueryEncoder()
encoder.encode(id, forKey: "id")
print(encoder.queryItems)
// [URLQueryItem(name: "id", value: "5")]
By default, optional values are not encoded.
var id: Int?
let encoder = URLQueryEncoder()
encoder.encode(id, forKey: "id")
print(encoder.queryItems)
// []
Encoding Arrays
let ids = [3, 4, 5]
let encoder = URLQueryEncoder()
encoder.encode(ids, forKey: "id")
// Query: "id=3&id=4&id=5"
With an explode option disabled:
let ids = [3, 4, 5]
let encoder = URLQueryEncoder()
encoder.encode(ids, forKey: "id", explode: false)
// Query: "id=3,4,5"
With an explode option disabled and a custom delimiter:
let ids = [3, 4, 5]
let encoder = URLQueryEncoder()
encoder.encode(ids, forKey: "id", explode: false, delimeter: "|")
// Query: "id=3|4|5"
Encoding Objects
let user = User(role: "admin", name: "kean")
let encoder = URLQueryEncoder()
encoder.encode(user, forKey: "id")
// Query: "role=admin&name=kean"
With an explode option disabled:
let user = User(role: "admin", name: "kean")
let encoder = URLQueryEncoder()
encoder.encode(user, forKey: "id", explode: false)
// Query: "id=role,admin,name,kean"
As a "deep" object:
let user = User(role: "admin", name: "kean")
let encoder = URLQueryEncoder()
encoder.encode(user, forKey: "id", isDeepObject: true)
// Query: "id[role]=admin&id[name]=kean")"
If you are encoding a request body using URL-form encoding, you can use a convenience
URLQueryEncoder.encode(_:)method.
Encoding Options
There are two ways to change the encoding options. You can set them directly on URLQueryEncoder instance.
let encoder = URLQueryEncoder()
encoder.explode = false
encoder.isDeepObject = true
encoder.delimiter = "|"
encoder.dateEncodingStrategy = .millisecondsSince1970
Or pass options in each individual encode call.
let user = User(role: "admin", name: "kean")
let ids = [3, 4, 5]
let encoder = URLQueryEncoder()
encoder.encode(ids, forKey: "ids", explode: false)
encoder.encode(ids, forKey: "ids2", explode: true)
encoder.encode(user, forKey: "user", isDeepObject: true)
encoder.encode(2, forKey: "id")
// Query: "ids=3,4,5&ids2=3&ids2=4&ids2=5&user[role]=admin&user[name]=kean&id=2"
The reason it's designed this way is that in OpenAPI each parameter can come with different serialization options.
Accessing Results
You can access the encoding results at any time, and they come in different forms:
public final class URLQueryEncoder {
// Encoded query items.
public var queryItems: [URLQueryItem]
// Encoded query items as name-value pairs.
public var items: [(String, String?)]
// The encoded query items as a URL query subcomponent.
public var query: String?
// The encoded query items as a URL query subcomponent with percent-encoded values.
public var percentEncodedQuery: String?
}
License
URLQueryEncoder is available under the MIT license. See the LICENSE file for more info.
286 Dec 23, 2022
3 Dec 15, 2022
393 Jan 5, 2023
567 Dec 17, 2022
369 Sep 28, 2022
454 Oct 30, 2022
364 Sep 28, 2022
60 Aug 21, 2022
2 Sep 11, 2021
6 Sep 1, 2022
1.5k Dec 20, 2022
2.5k Dec 21, 2022
736 Nov 3, 2022
145 Sep 10, 2022
13 Oct 25, 2022
30 Oct 19, 2022
5 Aug 17, 2021
15 Dec 3, 2022
![Dictionary of [String: Object] not encoded correctly?](https://avatars.githubusercontent.com/u/2995710?v=4)
362 Jul 1, 2022
0 Jan 15, 2022
475 Dec 20, 2022
11 Sep 13, 2022
3 May 11, 2022
19 Nov 25, 2022
60 Dec 12, 2022
331 May 23, 2021
568 Jan 5, 2023