How to provide a different example Response for a type for different endpoint paths?
dcs3spp opened this issue · comments
Hi,
I am working with a codebase that has has the following type to record the status of operations on key resources.
type apiModifyKeySuccess struct {
Key string `json:"key" example:"12345678987654321"`
Status string `json:"status"` example:"ok"`
Action string `json:"action"` example:"added"`
KeyHash string `json:"key_hash,omitempty"` example:"bc123456"
}
The Action field can accept values added, deleted or modified
I have used the example tag to give example values for the response in the OAS generated documentation. However, this example is generated globally across all endpoints.
For example, endpoint paths for adding and deleting a key render the same example response with Action example value being displayed as "added".
Is it possible to use the @success tag to override the example for the type?
// @Title Create a key.
// @Description Create a new key and return associated details in response.
// @Param key body user.SessionState true "Info for key relating to access rights, policies etc."
// @Success 201 object apiModifyKeySuccess "JSON response containing the new key and hash
// @Resource keys
// @Route /api/keys [post]
func AddKey() {
// ...
}
// @Title Delete a key.
// @Description Delete a given key.
// @Param keyID path string true "Id of a specific key."
// @Success 200 object apiModifyKeySuccess "Returns details of the key and confirmation of deletion action"
// @Resource keys
// @Route /api/keys [delete]
func DeleteKey() {
// ...
}