protoc-gen-swagger: honor example field of message option #799
Conversation
|
Yeah sure, will do that in the next days. Would be great if you could give some input regarding examples for fields. I'd really like to have that, but it would require changes in the .proto files.. and it may not look very nice to have the "example" option in JSONSchema (See https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-swagger/options/openapiv2.proto) as well. I guess there was a good reason to use JSONSchema instead of Schema for fields. |
Codecov Report
@@ Coverage Diff @@
## master #799 +/- ##
==========================================
- Coverage 53.27% 53.21% -0.07%
==========================================
Files 30 30
Lines 3369 3373 +4
==========================================
Hits 1795 1795
- Misses 1399 1403 +4
Partials 175 175
Continue to review full report at Codecov.
|
|
I don't know about the Schema vs JSONSchema for fields (@ivucica might know) but as for adding an example to the example files, that should be pretty straight forward I hope? It's the easiest way to show the users how to specify these things in their own files, so it should be comprehensive (as you say, include some nested type examples) |
|
Hah yeah it's clear how to add usage examples. Confusing with the "examples" word all over the place. I was just curious about the "example option field", and if we maybe can work on a possibility to expand this to proto fields as well (and not just for messages, which this patch adds) Edit: Code sample for clarity: (which is not syntactically correct, because it's actually the sub-field "value" inside of example, but whatever) anyway, the above is not possible, because openapiv2_field = JSONSchema and not Schema, which does not contain the example option field. |
with json.RawMessage, users can supply complete json for swagger objects (i.e.
for a proto Message). If it's correct json, it will be added to the output.json
and rendered correctly by consuming applications (i.e. code generators or
swagger-ui)
Example, in proto:
option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
example: {
value:
'{"someKey" : "someValue", "anotherKey" : 5}';
};
};
Rendered JSON:
"example": {
"someKey": "someValue",
"anotherKey": 5
}
If we used string instead of json.RawMessage, the serializer would escape the
quotes and it would be serialized as a string. This is not desirable, because
the output should be in fact JSON key/value pairs.
|
🏓 this would really be a nice feature. LMK if there's anything I could help with... 🤔 |
|
If you want to fork this and take over please feel free @srenatus |
|
As discussed, we're happy to merge this as is and add tests separately. Thanks for your contribution @birdayz! |
I don't see a possibility to set example values through options. These would be shown by e.g. swagger-ui as example bodies for a POST.
But it also allows setting the example field for nested messages, and the code generator will honor this and just set the nested field to the value.
One thing would be missing: setting examples for fields, i.e. for the string "name" in the example above. sadly this would need deeper changes, as the field option uses a different data type: JSONSchema and not Schema. Schema contains the example field..
I wonder why this is the case. As far as i have seen, it's possible in Swagger to set the example field even for "primitives".
This patch makes it possible to set examples for messages. While not perfect, it can be a way out of this.
If there's a better possibility to provide examples - without editing the .json manually, please tell me ;)