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.
@devshorts @xiaodongw The current
responseWith
function JSON serializes the example response object and then passes that into the Swagger-API library’ssetExample
function. The results is that the example is listed as the JSON serialized object which is not the expected behavior for Swagger Response types. According the the Swagger documentation, response body examples are expected to return a list of the object properties for object response types. https://swagger.io/docs/specification/adding-examples/. I am including an example of how Swagger expects examples to work in a response body based on the specification:responses: '200': description: A user object. content: application/json: schema: $ref: '#/components/schemas/User' # Reference to an object example: # Properties of the referenced object id: 10 name: Jessica Smith
Since the swagger-api library used here to
setExample
seems to be correctly returning the object properties to be listed in the example (as the Swagger specification expects) I am proposing to pass in the actual object example and not a JSON serialized version of the object. I am including an example of what a Response Body Example looks like in the Swagger doc with these changes (the example lists the object properties, as the Swagger Specification says it should) and without these changes (the example is a string representing the JSON serialized object, which is not how the Swagger specification expects response examples to be).Response Example Object When Passing the Object to SetExample:
"/students/{id}":{ "get":{ "tags":[ "Student" ], "summary":"Read student information", "description":"Read the detail information about the student.", "produces":[ "application/json" ], "parameters":[ { "name":"id", "in":"path", "description":"the student id", "required":true, "type":"string" } ], "responses":{ "200":{ "description":"the student object", "schema":{ "example":{ "first_name":"Tom", "last_name":"Wang", "gender":"Male", "birthday":{ }, "grade":4, "address":{ "street":"California Street", "zip":"94111" } }, "$ref":"#/definitions/Student" } },
Response Example Object When Passing the JSON serialized Object to SetExample:
"/students/{id}":{ "get":{ "tags":[ "Student" ], "summary":"Read student information", "description":"Read the detail information about the student.", "produces":[ "application/json" ], "parameters":[ { "name":"id", "in":"path", "description":"the student id", "required":true, "type":"string" } ], "responses":{ "200":{ "description":"the student object", "schema":{ "example":"{\"first_name\":\"Tom\",\"last_name\":\"Wang\",\"gender\":\"Male\",\"birthday\":{\"weekyear\":2017,\"chronology\":{\"zone\":{\"fixed\":true,\"id\":\"UTC\"}},\"month_of_year\":11,\"week_of_weekyear\":45,\"year_of_era\":2017,\"year_of_century\":17,\"century_of_era\":20,\"era\":1,\"day_of_year\":311,\"day_of_week\":2,\"day_of_month\":7,\"year\":2017,\"fields\":[{\"leap_duration_field\":{\"precise\":true,\"unit_millis\":86400000,\"name\":\"days\",\"type\":{\"name\":\"days\"},\"supported\":true},\"minimum_value\":-292275054,\"maximum_value\":292278993,\"lenient\":false,\"duration_field\":{\"precise\":false,\"unit_millis\":31556952000,\"name\":\"years\",\"type\":{\"name\":\"years\"},\"supported\":true},\"name\":\"year\",\"type\":{\"duration_type\":{\"name\":\"years\"},\"name\":\"year\"},\"supported\":true},{\"range_duration_field\":{\"precise\":false,\"unit_millis\":31556952000,\"name\":\"years\",\"type\":{\"name\":\"years\"},\"supported\":true},\"leap_duration_field\":{\"precise\":true,\"unit_millis\":86400000,\"name\":\"days\",\"type\":{\"name\":\"days\"},\"supported\":true},\"minimum_value\":1,\"maximum_value\":12,\"lenient\":false,\"duration_field\":{\"precise\":false,\"unit_millis\":2629746000,\"name\":\"months\",\"type\":{\"name\":\"months\"},\"supported\":true},\"name\":\"monthOfYear\",\"type\":{\"duration_type\":{\"name\":\"months\"},\"range_duration_type\":{\"name\":\"years\"},\"name\":\"monthOfYear\"},\"supported\":true},{\"range_duration_field\":{\"precise\":false,\"unit_millis\":2629746000,\"name\":\"months\",\"type\":{\"name\":\"months\"},\"supported\":true},\"minimum_value\":1,\"maximum_value\":31,\"duration_field\":{\"precise\":true,\"unit_millis\":86400000,\"name\":\"days\",\"type\":{\"name\":\"days\"},\"supported\":true},\"unit_millis\":86400000,\"lenient\":false,\"name\":\"dayOfMonth\",\"type\":{\"duration_type\":{\"name\":\"days\"},\"range_duration_type\":{\"name\":\"months\"},\"name\":\"dayOfMonth\"},\"supported\":true}],\"field_types\":[{\"duration_type\":{\"name\":\"years\"},\"name\":\"year\"},{\"duration_type\":{\"name\":\"months\"},\"range_duration_type\":{\"name\":\"years\"},\"name\":\"monthOfYear\"},{\"duration_type\":{\"name\":\"days\"},\"range_duration_type\":{\"name\":\"months\"},\"name\":\"dayOfMonth\"}],\"values\":[2017,11,7]},\"grade\":4,\"address\":{\"street\":\"California Street\",\"zip\":\"94111\"}}", "$ref":"#/definitions/Student" } },
Because this is not the expected behavior, I am unable to use other Swagger libraries that mock my service based on the FinatraSwagger generated swagger doc- the response type is not the object I am specifying the endpoint should respond with, but a JSON serialized version of the object. Is there a reason for JSON stringifying the object, or we can update this to just pass the example object to the setExample function, which seems to correctly handle listing properties of example objects/the example value objects? Note: I have also tested this with a string example and an int example, both return the actual example object as expected.