fix(openapi): let WithParameter reach the document - #69
Merged
Conversation
The option appended a ParameterDef to route metadata under "parameters", and the only two references to that key in the whole repository were the two lines doing the appending. The generator builds an operation's parameters from the path template, the query schema and the header schema, so a declaration made this way went into a map and stopped. It compiled, it ran, it returned no error, and the parameter reached no document and no generated client. That is a bad way for an option to fail. A route declaring a parameter the server honours would ship an OpenAPI document that never mentioned it, and the only way to find out was to read the generated spec and notice an absence. ParameterDef has a name, a location, a description, a required flag and an example, and the example is the only one of those that says anything about what the value holds. So that is what the schema is typed from. An int example gives an integer, a []string example gives an array of string, which is how you declare a repeatable parameter. With no example the parameter falls back to string, because a parameter with no schema is one no client can type at all. The typing runs through a throwaway schema generator with no component registry, so describing a parameter cannot register a component or leave a $ref pointing into one. Both branches of the operation builder converge before this runs, so a declaration behaves the same whether or not the handler takes a request struct. The already-collected parameters merge first, which means a name described by both a Go type and a declaration keeps the type-derived version. That is the precedence the three existing sources already use among themselves, and it is the right way round: the type knows the real shape, a declaration only knows what somebody typed into the call. A path parameter comes out required whatever the declaration says, since OpenAPI does not accept one that claims otherwise.
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Conventional Commits ValidationPR Title: valid |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The option appended a ParameterDef to route metadata under "parameters", and the only two references to that key in the whole repository were the two lines doing the appending. The generator builds an operation's parameters from the path template, the query schema and the header schema, so a declaration made this way went into a map and stopped. It compiled, it ran, it returned no error, and the parameter reached no document and no generated client.
That is a bad way for an option to fail. A route declaring a parameter the server honours would ship an OpenAPI document that never mentioned it, and the only way to find out was to read the generated spec and notice an absence.
ParameterDef has a name, a location, a description, a required flag and an example, and the example is the only one of those that says anything about what the value holds. So that is what the schema is typed from. An int example gives an integer, a []string example gives an array of string, which is how you declare a repeatable parameter. With no example the parameter falls back to string, because a parameter with no schema is one no client can type at all. The typing runs through a throwaway schema generator with no component registry, so describing a parameter cannot register a component or leave a $ref pointing into one.
Both branches of the operation builder converge before this runs, so a declaration behaves the same whether or not the handler takes a request struct. The already-collected parameters merge first, which means a name described by both a Go type and a declaration keeps the type-derived version. That is the precedence the three existing sources already use among themselves, and it is the right way round: the type knows the real shape, a declaration only knows what somebody typed into the call.
A path parameter comes out required whatever the declaration says, since OpenAPI does not accept one that claims otherwise.