@devshorts @xiaodongw The current responseWith function JSON serializes the example response object and then passes that into the Swagger-API library’s setExample 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](https://github.com/swagger-api/swagger-core/blob/76465b169f96652e8af9c9ded4b4bfcc17a336c9/modules/swagger-models/src/main/java/io/swagger/models/properties/ObjectProperty.java) used here tosetExample` 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.
@devshorts @xiaodongw The current
responseWithfunction JSON serializes the example response object and then passes that into the Swagger-API library’ssetExamplefunction. 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
Since the [swagger-api library](https://github.com/swagger-api/swagger-core/blob/76465b169f96652e8af9c9ded4b4bfcc17a336c9/modules/swagger-models/src/main/java/io/swagger/models/properties/ObjectProperty.java) used here tosetExample` 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.