Repository navigation
update http library documentation for @encode to explicitly call out encoder intent #2256
Description
The "Next" version of the docs for the HTTP library says:
I interpret this to mean that if a TypeSpec definition imports the http library, then any emitter, including the openapi3 emitter, will treat a utcDateTime in a header as rfc7231. For the openapi3 emitter, that means the header will be rendered with "format: http-date-rfc7231", but this is not the behavior I see in the playground.
Activity
timotheeguerin commentedon Aug 8, 2023
Yeah the doc is correct, the openapi3 emitter should be fixed.
timotheeguerin commentedon Aug 8, 2023
I think autorest does it correctly
edit: nvm it doesn't either
mikekistler commentedon Aug 8, 2023
I think the key concern for me is that this doc is for http library -- not the emitters. I don't think the http library currently does any defaulting of encode values for any type. We could change the openapi3 and autorest emitters to implement this behavior, but it would still be incorrect to document this for the http library.
timotheeguerin commentedon Aug 8, 2023
I disagree, the http libraries makes some assumption of what the typespec means in many ways. If we have this default then it has to be set by http library. You can’t have every emitter interpret it their own way and then be incompatible with each other.
If we don’t want to have this default at all we can discuss it but as far as I remember dpg emitters already respect this behavior
mikekistler commentedon Aug 8, 2023
Sorry if I wan't clear. I did not mean to imply that the http library shouldn't do this.
My point was that to make the doc accurate we need to change the http library and not the openapi3 and autorest emitters.
markcowl commentedon Aug 9, 2023
est: 1
Update documentation to indicate emitters should interprest these values this way
[-]http library documentation for `@encode` is incorrect or at least misleading[/-][+]update http library documentation for `@encode` to explicitly call out encoder intent[/+]mikekistler commentedon Aug 13, 2023
Should I open a separate issue to fix the autorest and openapi3 emitters?
timotheeguerin commentedon Aug 14, 2023
Yeah maybe be good
markcowl commentedon Aug 29, 2023
Mike Kistler (@mikekistler) yes
Clarify default encoding responsability (#2387)