czechboy0
commented
2 months ago Hi @JetForMe,
I understand your desire to write against code that is more ergonomic, but note that this project's goal is to generate a type-safe Swift representation of an OpenAPI document, which in turn describes HTTP communication (read more about this project's scope and goals here: https://swiftpackageindex.com/apple/swift-openapi-generator/1.2.1/documentation/swift-openapi-generator/project-scope-and-goals).
So not only is the fact that you work with the type-safe representation of the HTTP communication necessary, it's very much intentional. The generated code is meant to help developers only send and receive valid HTTP requests and responses according to the OpenAPI document. It saves you from writing the hundreds of lines of boilerplate code per operation, however at the end of the day, you are still responsible for interpreting what the individual HTTP requests and responses mean for your application. There's no way that the generator can know that, so it can't generate it for you either.
Note that for client code, last year we added a shorthand API, as often a client only wants to handle one specific status code and content type, and simply throw an error if it's different. That's because there's usually a single service implementation but many different client implementations (so each might need a different subset of the API).
We didn't add such shorthand API for unwrapping the Input, because the server must handle all the request flavors that the OpenAPI document describes, so in your case, it's likely that you want a switch statement for the content types supported (even if you currently only support one - JSON).
let deviceIDs = json.deviceID
This is unexpected - if the device must have a valid deviceID, you should mark it as required in the OpenAPI document, meaning that the handler won't even be called if the ID is missing, simplifying your code further.
Then, your handler could look something like this (with the recommended error handling):
func registerAPNDevice(_ inInput: Operations.registerAPNDevice.Input) async throws -> Operations.registerAPNDevice.Output {
let requestBody: Operations.registerAPNDevice.Input.bodyPayload
switch inInput.body {
case .json(let json):
requestBody = json
}
guard let deviceID = UUID(uuidString: requestBody.deviceID) else {
// return 400, as the deviceID is not a valid UUID string, so this is client request error
}
print("DeviceID: \(deviceID)")
return .created(.init())
}If you have feedback that can make working with the HTTP requests/responses more ergonomic without trying to wrap them or hide away any expressivity, please file individual issues where we can discuss each one. But hopefully the above sheds more light on why the generated code works this way, and that at a high level, it's in line with this project's goals.
simonjbeaumont
JetForMe
Motivation
Migrating from writing Swift Vapor controllers directly to using Open API, I've found the latter to be substantially more cumbersome. A simple POST handler in Vapor might look like this:
To my novice use of the generated code, I have to write this:
Additionally, it took me far too long to figure out how to write this code. Xcode’s code completion rarely works reliably for me, which didn’t help. But I spent a lot of time just trying to drill down through the hierarchy of data structures to get at the data I needed (the request content).
The client side isn't much better:
This exposes in the client the internal structure of the request (JSON in the body). It would be better to have Swift struct as an abstraction that one hands to the generated code, which is responsible for packaging it and sending it to the server.
I was directed to this example recently, but honestly it doesn't feel any better. The code is littered with boilerplate (lots of
.init(), for example).Proposed solution
The generator should generate additional accessor functions to streamline access to the values. I'm not really sure exactly what the form of this should take is, but the
Inputobject should have methods or properties that let me get directly at the content I want. Don't make my handler dig through the HTTP structure to get at it. Similarly for the client side, don't make the code expose the HTTP structure.Alternatives considered
No response
Additional information
No response