Restore `type` attributes on operations object to remain compliant with 1.2 spec.

[STRML]

Discussion migrated from this commit comment.

As mentioned on this swagger-spec issue, this is required to be compliant with the spec but simply not quite clearly worded.

I don't think we should put this behind an option as we would essentially be allowing users to create noncompliant output, which can break outside tooling.

It seems to me that GoDaddy doesn't need multiple response types, so much as they need one response type and multiple error types. Would it not make sense to do something more like the following:

{
  "path": "/user/walletHistory",
  "operations": [{
    "method": "GET",
    "nickname": "getWalletHistory",
    "parameters": [],
    "responseMessages": [{
      "code": 200,
      "message": "Request was successful"
    }, {
      "code": 401,
      "message": "Unauthorized",
      "responseModel": "error"
    }, {
      "code": 404,
      "message": "Not Found",
      "responseModel": "error"
    }],
    "type": "array",
    "items": {
      "type": "transaction"
    }
  }]
}

This produces something like this, which eliminates the redundancy by excluding the responseModel from the 200.

[bajtos]

Here is @shelbys' comment on the matter:

We switched to always using responseMessage.responseModel, because we use different Models by Status, including a custom, reusable Model for Error responses. This is more natural for many of our endpoints that aren't CRUD-related. Also, I believe it better uses the space visually and with less confusion.

You could change it to use type if there aren't multiple possible, but we'd never use that since we always have multiple

For reference, see: https://developer.godaddy.com/doc#!/shoppers/Subaccount_create

If we remove the type description from 200 response messages and don't provide config option to re-enable it, then GoDaddy can still get the UI they want by modifying their SwaggerUI fork to patch 200/204 response messages with the global operation type. That way the Swagger descriptor of GoDaddy API remains valid, and the web GUI has the compact form as desired.

Is that ok with you, @shelbys?

[shelbys]

@bajtos - I don't understand what you mean by modifying their SwaggerUI fork to patch 200/204 response messages with the global operation type. Is this something that you believe is specific to GoDaddy, and therefore should stay in our fork?

//CC @dashby3000

[STRML]

I agree that it is much more visually appealing to have the return type under the 200 responseMessage rather than in that huge section in the top.

Perhaps we would have some luck getting a change merged into swagger-ui that creates a default 200 section if none is specified. In the 2.0 spec, responseMessages is moved to responses and becomes required anyhow.

On Nov 10, 2014, at 7:10 PM, Shelby Sanders notifications@github.com wrote:

@bajtos https://github.com/bajtos - I don't understand what you mean by modifying their SwaggerUI fork to patch 200/204 response messages with the global operation type. Is this something that you believe is specific to GoDaddy, and therefore should stay in our fork?

//CC @dashby3000 https://github.com/dashby3000
—
Reply to this email directly or view it on GitHub #75 (comment).

[bajtos]

@shelbys

So the idea is that loopback-explorer will return a Swagger operation with an empty response model for 200/204.

{
    "method": "GET",
    "nickname": "User_find",
    "parameters": [],
    "responseMessages": [{
      "code": 200,
      "message": "Request was successful"
    }, {
      "code": 404,
      "message": "Not Found",
      "responseModel": "error"
    }],
    "type": "array",
    "items": {
      "type": "User"
    }
  }

Now it's up to the SwaggerUI (either GoDaddy's fork, or the official one as suggested by @STRML) to detect the situation and pull the 200 response type from the operation type.

Does it make sense now?

[STRML]

I think this is additionally needed for arrays; I don't see any spec-compliant way to supply an array response (say, an array of models) using the responseMessages format.

[shelbys]

@STRML - Agreed array of models is necessary. So far, we've been using [ModelName] to indicate collections, but that's more of a workaround. I assume Swagger will officially head to toward the "Data Type Fields" (e.g. type, items, and $ref)

[bajtos]

I am proposing to move on and implement @STRML's proposal.

[STRML]

See #80 for implementation of this.