How to provide a different example Response for a type for different endpoint paths?

[dcs3spp]

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() {
  // ...
}