Skip to content

Commit 7186fd5

Browse files
czechboy0czechboy0
authored
[Docs] Document the Converter type and all the cases it needs to support (#50)
[Docs] Document the Converter type and all the cases it needs to support ### Motivation I wrote down how the Converter works and all the cases we need to support. That'll help prepare ground for the refactor needed for #43. Also created space for maintainer-focused docs. ### Modifications Added docs, which I'll use in a subsequent PR to ensure all the cases listed are implemented and tested. ### Result Converter now has higher level docs, and maintainers have a place to add more docs. ### Test Plan Previewed locally. Reviewed by: simonjbeaumont Builds: ✔︎ pull request validation (5.8) - Build finished. ✔︎ pull request validation (5.9) - Build finished. ✔︎ pull request validation (nightly) - Build finished. ✔︎ pull request validation (soundness) - Build finished. #50
1 parent 64b199d commit 7186fd5

File tree

3 files changed

+141
-0
lines changed

3 files changed

+141
-0
lines changed

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

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Converting between data and Swift types
2+
3+
Learn about the type responsible for convertering between binary data and Swift types.
4+
5+
## Overview
6+
7+
The [`Converter`](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Conversion/Converter.swift) type is a structure defined in the runtime library and is used by both the client and server generated code to perform conversions between binary data and Swift types.
8+
9+
> Note: `Converter` is one of the SPI types, not considered part of the public API of the runtime library. However, because generated code relies on it, SPI stability needs to be considered when making changes to it and to the generator.
10+
11+
Most of the functionality of `Converter` is implemented as helper methods in extensions:
12+
- [`Converter+Client.swift`](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Conversion/Converter%2BClient.swift)
13+
- [`Converter+Server.swift`](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Conversion/Converter%2BServer.swift)
14+
- [`Converter+Common.swift`](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Conversion/Converter%2BCommon.swift)
15+
16+
Some helper methods can be reused between client and server code, such as headers, but most can't. It's important that we only generalize (move helper methods into common extensions) if the client and server variants would have been exact copies. However, if there are differences, prefer to keep them separate and optimize each variant (for client or server) separately.
17+
18+
### Generated code and generics interaction
19+
20+
As outlined in <doc:Project-scope-and-goals>, we aim to minimize the complexity of the generator and rely on the Swift compiler to help ensure that if generated code compiles, it's likely to work correctly.
21+
22+
To that end, if the input OpenAPI document contains an input that Swift OpenAPI Generator doesn't support, our first preference is to catch it in the generator and emit a descriptive diagnostic. However, there are cases where that is prohibitively complex, and we let the Swift compiler ensure that, for example, an array of strings cannot be used as a path parameter. In this example case, the generator emits code with the path parameter being of Swift type `[String]`, but since there doesn't exist a converter method for it, it will fail to build. This is considered expected behavior.
23+
24+
In the case of the converter, it contains helper methods for all the supported combinations of an schema location, a "coding strategy" and a Swift type.
25+
26+
### Dimensions of helper methods
27+
28+
Below is a list of the "dimensions" across which the helper methods differ:
29+
30+
- **Client/server** represents whether the code is needed by the client, server, or both ("common").
31+
- **Set/get** represents whether the generated code sets or gets the value.
32+
- **Schema location** refers to one of the several places where schemas can be used in OpenAPI documents. Values:
33+
- request path parameters
34+
- request query items
35+
- request header fields
36+
- request body
37+
- response header fields
38+
- response body
39+
- **Coding strategy** represents the chosen encoder/decoder to convert the Swift type to/from data. Values:
40+
- `JSON`
41+
- example: `application/json`
42+
- uses the type's `Codable` implementation and `JSONEncoder`/`JSONDecoder`
43+
- `text`
44+
- example: `text/plain`
45+
- uses the type's `LosslessStringConvertible` implementation, except for `Foundation.Date`, which uses a system date formatter
46+
- `binary`
47+
- example: `application/octet-stream`
48+
- doesn't transform the binary data, just passes it through
49+
- serves as the fallback for content types that don't have more specific handling
50+
- **Swift type** represents the generated type in Swift that best represents the JSON schema defined in the OpenAPI document. For example, a `string` schema is generated as `Swift.String`, an `object` schema is generated as a Swift structure, and an `array` schema is generated as a `Swift.Array` generic over the element type. For the helper methods, it's important which protocol they conform to, as those are used for serialization. Values:
51+
- _string-convertible_ refers to types that conform to `LosslessStringConvertible`
52+
- _array of string-convertibles_ refers to an array of types that conform to `LosslessStringConvertible`
53+
- _date_ is represented by `Foundation.Date`
54+
- _array of dates_ refers to an array of `Foundation.Date`
55+
- _codable_ refers to types that conform to `Codable`
56+
- _data_ is represented by `Foundation.Data`
57+
- **Optional/required** represents whether the method works with optional values. Values:
58+
- _required_ represents a special overload only for required values
59+
- _optional_ represents a special overload only for optional values
60+
- _both_ represents a special overload that works for optional values without negatively impacting passed-in required values (for example, setters)
61+
62+
### Helper method variants
63+
64+
Together, the dimensions are enough to deterministically decide which helper method on the converter should be used.
65+
66+
In the list below, each row represents one helper method.
67+
68+
| Client/server | Set/get | Schema location | Coding strategy | Swift type | Optional/required | Method name |
69+
| --------------| ------- | --------------- | --------------- | ---------- | ------------------| ----------- |
70+
| common | set | header field | text | string-convertible | both | TODO |
71+
| common | set | header field | text | array of string-convertibles | both | TODO |
72+
| common | set | header field | text | date | both | TODO |
73+
| common | set | header field | text | array of dates | both | TODO |
74+
| common | set | header field | JSON | codable | both | TODO |
75+
| common | get | header field | text | string-convertible | optional | TODO |
76+
| common | get | header field | text | string-convertible | required | TODO |
77+
| common | get | header field | text | array of string-convertibles | optional | TODO |
78+
| common | get | header field | text | array of string-convertibles | required | TODO |
79+
| common | get | header field | text | date | optional | TODO |
80+
| common | get | header field | text | date | required | TODO |
81+
| common | get | header field | text | array of dates | optional | TODO |
82+
| common | get | header field | text | array of dates | required | TODO |
83+
| common | get | header field | JSON | codable | optional | TODO |
84+
| common | get | header field | JSON | codable | required | TODO |
85+
| client | set | request path | text | string-convertible | both | TODO |
86+
| client | set | request path | text | date | both | TODO |
87+
| client | set | request query | text | string-convertible | both | TODO |
88+
| client | set | request query | text | array of string-convertibles | both | TODO |
89+
| client | set | request query | text | date | both | TODO |
90+
| client | set | request query | text | array of dates | both | TODO |
91+
| client | set | request query | text | array of dates | both | TODO |
92+
| client | set | request body | text | string-convertible | optional | TODO |
93+
| client | set | request body | text | string-convertible | required | TODO |
94+
| client | set | request body | text | date | optional | TODO |
95+
| client | set | request body | text | date | required | TODO |
96+
| client | set | request body | JSON | codable | optional | TODO |
97+
| client | set | request body | JSON | codable | required | TODO |
98+
| client | set | request body | binary | data | optional | TODO |
99+
| client | set | request body | binary | data | required | TODO |
100+
| client | get | response body | text | string-convertible | required | TODO |
101+
| client | get | response body | text | date | required | TODO |
102+
| client | get | response body | JSON | codable | required | TODO |
103+
| client | get | response body | binary | data | required | TODO |
104+
| server | get | request path | text | string-convertible | optional | TODO |
105+
| server | get | request path | text | string-convertible | required | TODO |
106+
| server | get | request path | text | date | optional | TODO |
107+
| server | get | request path | text | date | required | TODO |
108+
| server | get | request query | text | string-convertible | optional | TODO |
109+
| server | get | request query | text | string-convertible | required | TODO |
110+
| server | get | request query | text | array of string-convertibles | optional | TODO |
111+
| server | get | request query | text | array of string-convertibles | required | TODO |
112+
| server | get | request query | text | date | optional | TODO |
113+
| server | get | request query | text | date | required | TODO |
114+
| server | get | request query | text | array of dates | optional | TODO |
115+
| server | get | request query | text | array of dates | required | TODO |
116+
| server | get | request body | text | string-convertible | optional | TODO |
117+
| server | get | request body | text | string-convertible | required | TODO |
118+
| server | get | request body | text | date | optional | TODO |
119+
| server | get | request body | text | date | required | TODO |
120+
| server | get | request body | JSON | codable | optional | TODO |
121+
| server | get | request body | JSON | codable | required | TODO |
122+
| server | get | request body | binary | data | optional | TODO |
123+
| server | get | request body | binary | data | required | TODO |
124+
| server | set | response body | text | string-convertible | required | TODO |
125+
| server | set | response body | text | date | required | TODO |
126+
| server | set | response body | JSON | codable | required | TODO |
127+
| server | set | response body | binary | data | required | TODO |

‎Sources/swift-openapi-generator/Documentation.docc/Development/Documentation-for-maintainers.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Documentation for maintainers
2+
3+
Learn about the internals of Swift OpenAPI Generator.
4+
5+
## Overview
6+
7+
Swift OpenAPI Generator contains multiple moving pieces, from the runtime library, to the generator CLI, plugin, to extension packages using the transport and middleware APIs.
8+
9+
Use the resources below if you'd like to learn more about how the generator works under the hood, for example as part of contribututing a new feature to it.
10+
11+
## Topics
12+
13+
- <doc:Converting-between-data-and-Swift-types>

‎Sources/swift-openapi-generator/Documentation.docc/Swift-OpenAPI-Generator.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ The generated code, runtime library, and transports are supported on more platfo
7676
- <doc:Project-scope-and-goals>
7777
- <doc:Contributing-to-Swift-OpenAPI-Generator>
7878
- <doc:Proposals>
79+
- <doc:Documentation-for-maintainers>
7980

8081
[openapi]: https://openapis.org
8182
[tools]: https://openapi.tools

0 commit comments

Comments
 (0)