Conversation
- a go struct tag that enables extensions to be introduced to the generated OpenAPI documents Signed-off-by: Chris Bygrave <chris.bygrave@kaleido.io>
Co-authored-by: Enrique Lacal <enrique.lacal@kaleido.io> Signed-off-by: Chris Bygrave <chris.bygrave@kaleido.io>
Signed-off-by: Chris Bygrave <chris.bygrave@kaleido.io>
EnriqueL8
left a comment
EnriqueL8
left a comment
There was a problem hiding this comment.
Looks good to me @chrisbygrave - thanks!
pkg/ffapi/openapi3.go
Outdated
| if tag == "" { | ||
| return nil | ||
| } | ||
| for _, extension := range strings.Split(tag, ",") { |
There was a problem hiding this comment.
The restriction that , is a special character for which there is no escape, probably needs calling out.
Another option would be to use query syntax parsing, which would mean & separator (rather than ,), but also a complete set of pre-built parsing logic and escaping rules
There was a problem hiding this comment.
My thinking here was to follow the pattern of https://github.com/invopop/jsonschema which provides jsonschema_extras which uses a comma separator. It looked like a reasonably popular package and so conforming with their spelling seemed appropriate.
Happy to re-work using query syntax parsing if we think that would be less restrictive though.
There was a problem hiding this comment.
Happy to see you take either as inspiration. I did take your hint to go and look at what invopop does on escaping:
https://github.com/invopop/jsonschema/blob/328cc73c3399c73df18b708fa00d29669cb0e4cc/reflect.go#L1121-L1144
pkg/ffapi/openapi3.go
Outdated
| if ffEnum := tag.Get("ffenum"); ffEnum != "" { | ||
| schema.Enum = fftypes.FFEnumValues(ffEnum) | ||
| } | ||
| if ffExtensions := tag.Get("ffextensions"); ffExtensions != "" { |
There was a problem hiding this comment.
type TestExtensions struct {
MyString string `ffstruct:"mystruct" json:"mystring" ffextensions:"x-key=value"`
}I found ffextensions a little hard as a term here. All the ffxyz tags are "extensions", so it's a little bit of a mental jump from ffextensions to "These key+value pairs will make their way into the JSON schema, as extensions under the type of this field".
My counter proposal is probably ffschemaext (I think ffschemaextensions is way too long)
peterbroadhurst
left a comment
peterbroadhurst
left a comment
There was a problem hiding this comment.
Couple of thoughts here @chrisbygrave
- ffextensions -> ffschemaext - use query-like format with well-defined escaping strategy Signed-off-by: Chris Bygrave <chris.bygrave@kaleido.io>
|
Thanks for the steer @peterbroadhurst - I've updated the PR to support query syntax parsing, and added a couple of tests to catch encoding issues. I've also switched out |
3 participants
This PR adds support for a gostruct tag
ffextensionsthat allows a comma-separated list of key/value pairs to be added as extensions to the schema generated into the OpenAPI document. Keys must be of the formatx-<name>.For example, the following structure:
Would generate a schema: