Add SOAR-0007 proposal: Shorthand APIs for inputs and outputs #291
Conversation
Signed-off-by: Si Beaumont <[email protected]>
|
This proposal is now In Review, which will run until September 29 - feel free to leave your feedback either on this PR or on the corresponding Swift Forums post. Thanks @simonjbeaumont for the write-up! |
|
Also from my side, thank you for this proposal! I think it will really simplify many use-cases where the client component of the generator is used. |
|
@yanniks thanks for taking the time to provide feedback!
Could you clarify, in this event, what information would you need and what would you want to do with it? Pulling out the relevant section of the proposal content to discuss further1: // A throwing computed property is generated for each documented outcome.
var ok: Operations.getGreeting.Output.Ok {
get throws {
guard case let .ok(response) = self else {
// This error will be added to the OpenAPIRuntime library.
throw UnexpectedResponseError(expected: "ok", actual: self)
}
return response
}
}For example, if there was also a documented This proposal is specifically for simplifying the API when you want to continue if you get a specific response and don't want to be defensive in the case that any other response is received. In the event you do want to handle these other responses in a type-safe way, you can still do this, with the enum-based API. You can handle the ones you care about and use switch try await client.getGreeting(/* ... */) {
case .ok(let response):
print(try response.json.message) // <--- using `.json` shorthand API
case .notFound(_):
// ...
case .forbidden(_):
// ...
case .badRequest(_):
// ...
default:
// handle other response..
}If you're interested in always performing some behaviour for a given HTTP response regardless of the operation—e.g. logging errors, following redirects, or retrying on 503—then you should consider using a middleware for this. Footnotes |
|
Another related issue: #145 🙂 |
Signed-off-by: Si Beaumont <[email protected]>
|
@simonjbeaumont did not really think of using a middleware. In that case, I really support this proposal. Thanks for detailed reply! |
No problem! |
### Motivation The review period for SOAR-0007 (Shorthand APIs for inputs and outputs) has now concluded. This pull request adds the required SPIs to the runtime library to throw a runtime error when the response and/or body does not match that of the shorthand API being used. For further context, please review the proposal itself.[^1] [^1]: apple/swift-openapi-generator#291 ### Modifications - Extend `internal enum RuntimeError: Error` with two new cases: - `.unexpectedResponseStatus(expectedStatus:response:)` - `.unexpectedResponseBody(expectedContent:body:)` - Add SPI for generated code, to throw these errors: - `@_spi(Generated) public throwUnexpectedResponseStatus(expectedStatus:response:)` - `@_spi(Generated) public throwUnexpectedResponseBody(expectedStatus:body:)` ### Result Runtime library has two SPIs that can be used by the generator to implement the shorthand throwing getter APIs described in SOAR-0007. ### Test Plan Companion PR in swift-openapi-generator. --------- Signed-off-by: Si Beaumont <[email protected]> Co-authored-by: Honza Dvorsky <[email protected]>
…tputs (#308) ### Motivation The review period for SOAR-0007 (Shorthand APIs for inputs and outputs) has now concluded. This pull request adds the required SPIs to the runtime library to throw a runtime error when the response and/or body does not match that of the shorthand API being used. For further context, please review the proposal itself.[^1] [^1]: #291 ### Modifications - Add support for computed properties with effects (e.g. throwing getters). - Generate a protocol extension to `APIProtocol` with an overload for each operation that lifts each of the parameters of `Input.init` as function parameters. - Generate a throwing computed property for each enum case related to a documented outcome, which will return the associated value for the expected case, or throw a runtime error if the value is a different enum case. ### Result Code that used to be written like this ```swift // before switch try await client.getGreeting(.init()) { case .ok(let response): switch response.body { case .json(let body): print(body.message) } case .undocumented(statusCode: _, _): throw UnexpectedResponseError() } // after print(try await client.getGreeting().ok.body.json.message) // ^ ^ ^ ^ // | | | `- (New) Throws if body did not conform to documented JSON. // | | | // | | `- (New) Throws if HTTP response is not 200 (OK). // | | // | `- (New) No need to wrap parameters in input value. // | // `- (Existing) Throws if there is an error making the API call. ``` ### Test Plan This PR includes updates to the various tests: - `SnippetBasedReferenceTests` - `FileBasedReferenceTests` - `PetstoreConsumerTests` ### Related Issues - Resolves #22 - Resolves #104 - Resolves #145 --------- Signed-off-by: Si Beaumont <[email protected]>
|
@swift-server-bot test this please |
Motivation
We'd like to run a proposal for generating additional API to simplify providing operation inputs and handling
operation outputs for simple API calls with just one successful outcome.
Modifications
(See the proposal itself for details)1
Result
n/a
Test Plan
n/a
Related Issues
#22, #104, #105, #145
Footnotes
https://github.com/apple/swift-openapi-generator/pull/291/files ↩