Right now you can specify multiple HTTP response status codes for successes and failures, but if they reuse the same struct in their response, which is likely if there is, say, a common error object, you can't specify multiple examples, e.g. an actual error you might see in a 400 response vs an error you might see in a 500 response. What I would like to see instead is a means of specifying multiple examples for a single struct. Adding it to the tags seems like it would be ugly so perhaps instead you could provide a means of reading comments per field. In the mean time I am going to modify the generated JSON by hand. One other possible solution is to declare additional structs solely for the purpose of documentation, but this has the obvious drawback of divorcing the documentation from the actual objects in the code.
Right now you can specify multiple HTTP response status codes for successes and failures, but if they reuse the same struct in their response, which is likely if there is, say, a common error object, you can't specify multiple examples, e.g. an actual error you might see in a 400 response vs an error you might see in a 500 response. What I would like to see instead is a means of specifying multiple examples for a single struct. Adding it to the tags seems like it would be ugly so perhaps instead you could provide a means of reading comments per field. In the mean time I am going to modify the generated JSON by hand. One other possible solution is to declare additional structs solely for the purpose of documentation, but this has the obvious drawback of divorcing the documentation from the actual objects in the code.