Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Swagger responseWith Example Update #40

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

Laura-Johannet-ZocDoc
Copy link

@Laura-Johannet-ZocDoc Laura-Johannet-ZocDoc commented Nov 9, 2017

@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 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant