`type` on `operation` object vs `responseMessage.responseModel`

[STRML]

When it comes to defining the return type of an operation, it appears that there are two valid ways to go.

The first is to define a type on the operation, e.g. like so:

{
  "path": "/user/login",
  "operations": [{
    "method": "POST",
    "nickname": "login",
    "parameters": [],
    "type": "User",
    "summary": "Log in."
  }]
}

The other is to define a responseModel as part of a responseMessage. This could be useful if multiple types of responses are possible. We discuss this in this loopback-explorer issue:

{
  "path": "/user/login",
  "operations": [{
    "method": "POST",
    "nickname": "login",
    "parameters": [],
    "responseMessages": [{
      "code": 200,
      "message": "Request was successful",
      "responseModel": "User"
    }],
    "summary": "Log in."
  }]
}

Which is the preferred style? If it is to use type, and to use responseMessages only for errors, could it be made more clear in the 1.2 spec that type is required?

[webron]

This is something that may be 'hidden' in the 1.2 spec, but if you read it thoroughly, it pretty much states that type is required.

If you look at https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#523-operation-object you'll see:
This object includes the Data Type Fields in order to describe the return value of the operation. The type field MUST be used to link to other models.

If you go to the Data Type Fields definition, you'll see there that type is mandatory. I agree it could have been clearer but we're not likely to modify that document right now.

In 1.2, it was assumed there's one main response and that would be used for the type, but that did not declare the HTTP Status Code.

In 2.0 we decided to remove the return type of the operation and keep it strictly with the response messages to avoid such ambiguity.

[STRML]

@webron Thanks, I really appreciate you chiming in on this. I will attempt to revert to type in our loopback-explorer implementation of 1.2, then we will move back to responseMessages.responseModel in 2.0.

[rajab57]

@webron
To clarify, for version 1.2 , is there a way to use type to return 2 models ? Or the response can only return 1 model ( can be nested ) ?

[webron]

@rajab57 - no matter which version of Swagger you use, you can only return 1 type of model. If you want to return several models that have a common ground (that is, at least one property that's common to them and can be used to distinguish between them), then you can use inheritance. Otherwise, only one model.