[Proposal] SOAR-0003: Type-safe Accept headers

Server Development
1

Hi Swift community,

The proposal SOAR-0003: Type-safe Accept headers for Swift OpenAPI Generator is now up and In Review.

The review period will run until 23rd August - please feel free to post your feedback either as a reply to this thread, or on the pull request.

cc @Honza_Dvorsky

5 Likes
2

Why other instead of undocumented (to match the existing, similar cases)?

3

Good catch - it's because while in the case of things like enums, the unknown values are genuinely undocumented and should only be an escape hatch, but in the case of the content types, there are genuine other values users might want to provide (like application/*) that are not generated.

So while "undocumented" is meant to convey that it shouldn't be used unless you really know what you're doing, "other" is less negative to reflect that there might be genuine cases of passing it without it being considered an anti-pattern or a workaround.

3 Likes
4 
extension Array {
    /// Returns the array sorted by the quality value, highest quality first.
    public func sortedByQuality<T>() -> [AcceptHeaderContentType<T>] where Element == Acceptable.AcceptHeaderContentType<T>, T : Acceptable.AcceptableProtocol
}

It's interesting, so .sortedByQuality() returns highest quality first (descending order), but .sorted(by: \.quality) returns the lowest quality first (ascending order).

Certainly has the potential to be confusing.

1 Like
5

Ooh, yeah, that's a good catch! Can sortedByQuality() just be removed, in preference to the more generic sorted(by:) (with an optional .reversed() as needed)? I suspect the runtime performance difference is negligible. It might be a bit less discoverable, but then again maybe not - Array's sorting methods are pretty well known, I have to think.

6

Ah sorry I was mistaken - QualityValue does not conform to Comparable, so people won't be able to write .sorted(by: \.quality) (they would need to write .sorted(by: \.quality.doubleValue), which is less likely to be confusing).

7

Well that just raises the question of why not? (QualityValue conforming to Comparable) It's just a floating point value.

8

The reason was exactly this - because the default sort is NOT what most people want. That's why we simply propose a dedicated method that returns the array sorted the way that is most useful.

1 Like
9

The review period for this proposal is now over. There were questions around the naming of "other" content types and the sorting of headers by their QualityValue (and its conformance to Comparable), which have been answered with no further changes.

The proposal is accepted. SOAR-0003 is now Ready for Implementation .

2 Likes