Even though the 3 exported functions on the provided module receive an operation ID as first parameter, the register function expects it on the same format as returned by the erf_parser module, while the other two functions expect it on the same format as the value on the user-provided OpenAPI spec. This should be object of discussion, because I feel the decision of snake-casing the operation ID to be used as ref to a request body schema/type should be a requirement when internally processing an operation ID and it's not properly documented. This will be specially relevant when documenting how to implement other spec parsers.
IMO provided code eases debugging the right module, but I would like to bring up to discussion the adequateness of the function names on the generated validation modules when it comes to be associated to a particular part/path on the user-provided spec. For instance, the following dbg trace shows a call to the function that validates the first of the possible request body schemas on the createUser operation of the users.openapi.json OpenAPI spec provided on the example.
I know that the '$.any_of' refers to the possible body schemas allowed for the operation, and that [0] means the first of them (this part about the [0] is not the one I'm concerned about), but I'm pretty sure I know this because I wrote a fair part of the code that puts their name on those functions. If we could find a better naming for those functions it would be great, specially for new devs coming to the project. Just wanted to let that written somewhere, even though I recognize that task is not easy and that we've discussed it enough at this point.
Closes #68
Two comments on the provided solution:
register
function expects it on the same format as returned by theerf_parser
module, while the other two functions expect it on the same format as the value on the user-provided OpenAPI spec. This should be object of discussion, because I feel the decision of snake-casing the operation ID to be used as ref to a request body schema/type should be a requirement when internally processing an operation ID and it's not properly documented. This will be specially relevant when documenting how to implement other spec parsers.dbg
trace shows a call to the function that validates the first of the possible request body schemas on thecreateUser
operation of theusers.openapi.json
OpenAPI spec provided on the example.I know that the '$.any_of' refers to the possible body schemas allowed for the operation, and that [0] means the first of them (this part about the [0] is not the one I'm concerned about), but I'm pretty sure I know this because I wrote a fair part of the code that puts their name on those functions. If we could find a better naming for those functions it would be great, specially for new devs coming to the project. Just wanted to let that written somewhere, even though I recognize that task is not easy and that we've discussed it enough at this point.