Multiple responses with the same response code and using data structures

[crwh05]

Aim: I want to use data structures so I can reuse the error responses in many request responses instead of having all the responses repeated throughout my code.

Like "Multiple response with the same status code" #113 I am getting this warning:

response payload `404` already defined for `GET` method

Here is an example of what I am trying to achieve.

## Dog [/dog/{id}]

Get a dog resource

+ Parameters

    + token: `OdBR7UNlXmJ7bp4eX` (string) - A unique account authentication token.
    + engine: `Default-Engine` (string) - Engine name.

### Dog [GET]

+ Response 200 (application/json)
    + Attributes (Dog)

+ Response 404 (application/json)
    + Attributes (UnknownDog)

+ Response 404 (application/json)
    + Attributes (OtherErrorMessage)

## Data Structures

### Dog
+ response
    + type: success
    + body: 
         + name: `Pedro`

### UnknownDog
+ response
    + type: error
    + body: `Unknown dog` (string)

### OtherErrorMessage
+ response
    + type: error
    + body: `Other error message` (string)

When I use json I can have multiple responses for the same status code, I only get the error when I use the data structures.

This below works fine.

+ Response 404 (application/json)

        {
            "response":{
                "type":"error",
                "body":"Unknown dog"
                }
            }
        }

+ Response 404 (application/json)

        {
            "response":{
                "type":"error",
                "body":"Other error message"
                }
            }
        }

Any suggestions how I can manage error responses so I dont have to repeat the responses for every request.

The main repeated error response is for authentication for example.

[ir-fuel]

If I do what you do (the last example) I get "response payload already defined for '....' method"

[pksunkara]

You can not define multiple responses with the same error code.

[ir-fuel]

That's why I don't understand it says "This below works fine", because it doesn't (imo it should be supported, if you want to provide multiple examples of for instance a http 400)

[kylef]

What's missing from the API Blueprint example above is that the request to make both types of 404 responses is the same.

You will need to defined the request example which would cause the particular response. While this isn't nessecery, you will get a warning when two identical requests would produces a response with the same status code, it isn't mandatory but you will get a warning to encourage you to document the differences.

For example, below I have documented that a request with a negative ID would cause one particular 404 error whereas a different also unknown positive ID would cause another type of 404 error.

FORMAT: 1A

# My API

## Dog [/dog/{id}]

Get a dog resource

+ Parameters
    + id: 1

### Dog [GET]

+ Response 200 (application/json)
    + Attributes (Dog)

+ Response 404 (application/json)
    + Attributes (UnknownDog)

+ Request
    + Parameters
        + id: `-1`

+ Response 404 (application/json)
    + Attributes (OtherErrorMessage)
        + response
            + body: An invalid number was supplied as ID

## Data Structures

### Dog
+ response
    + type: success
    + body
        + name: `Pedro`

### UnknownDog
+ response
    + type: error
    + body: `Unknown dog` (string)

### OtherErrorMessage
+ response
    + type: error
    + body: `Other error message` (string)