Additions to accept/returns type definitions

[STRML]

This relates to the Swagger 1.2 update at strongloop/loopback-component-explorer#14.

Swagger allows the display of model schemas inside the route definition, both as the return type:

And as a parameter type:

This requires that route definitions are able to mark their returns and accepts values as the model itself. Most built-in methods defined in dao.js (https://github.com/strongloop/loopback-datasource-juggler/blob/master/lib/dao.js#L1219) simply specify 'array' or 'object' as their return type, making it impossible to know the specifics of what they are returning.

I propose three new extensions to the accepts and returns syntax:

1. The addition of 'this' as a type definition (subclass object). In loopback-explorer, this would be interpreted as equal to the parent model.
2. Simple array syntax: {type: '[this]'}, {type: '[string]'}, etc., instead of the more verbose swagger-compliant {type: 'array', items: {type: 'string'}}. We should support both syntaxes in case of constraints on types, e.g. {type: 'array', items: {type: 'number', min: 0, max: 10}}.
3. Anonymous model definition. Sometimes methods don't return a model, but rather selected fields from a model, aggregations, or metadata. Rather than simply define 'object' or 'array' as the return type, it would be great to be able to define the return schema inline. Since constraints don't make sense on return properties, in my opinion it is not necessary to support the more verbose {type: ...} syntax. For example:

returns: {arg: 'data', root: true, type: 'object' /* or array */, schema: {
  field1: 'number',
  field2: 'string',
  field3: '[number]',
  field4: '[this]'
}},

[raymondfeng]

+1 for the general direction. This should be part of LDL:

• We can and should use the same syntax as the model property definition for types, for example:

{arg: 'name', type: String} // by type function
{arg: 'name', type: 'string'} // by type name
{arg: 'names', type: [String]} // string array
{arg: 'names', type: ['string']}
{arg: 'coordinate', type: {x: Number, y: Number}} // inline type def
{arg: 'customer', type: Customer} // ref a model

• I think we already introduce 'class' (or something similar) for 'this' in 2.x

[ritch]

Most built-in methods defined in dao.js (https://github.com/strongloop/loopback-datasource-juggler/blob/master/lib/dao.js#L1219) simply specify 'array' or 'object' as their return type, making it impossible to know the specifics of what they are returning.

In LoopBack 2.0 we specify the correct type for returns / accepts. This is not possible to implement in 1.0.

See: https://github.com/strongloop/loopback/blob/2.0/lib/models/persisted-model.js#L466

[STRML]

If it's in 2.0, I think that's more than fine; no reason to shoehorn it into 1.0.

[bajtos]

It would be great to verify the feature works as expected in loopback 2.0 + strong-remoting 2.0 + loopback-explorer 1.2, before we close this GH issue as resolved.

[ritch]

@STRML please chime in if you want to reopen this.

[STRML]

I still think the anonymous return schema would be useful; is there anything planned for that?

[JoeShi]

I have tried the following, and in the swagger, it does not show up the inline model. Please correct me

  Rail.remoteMethod('timetable', {
    accepts: [
      {arg: 'number', type: 'string', required: true},
      {arg: 'date', type: 'string', required: true, description: 'e.g. 2016-06-10'}
    ],
    returns: [
      {arg: 'number', type: 'string', required: true},
      {arg: 'date', type: 'string', required: true, description: 'e.g. 2016-06-10'},
      {arg: 'departure', type: 'string'},
      {arg: 'arrival', type: 'string'},
      {arg: 'stations', type: [{
        name: String,
        arrTime: String,
        depTime: String
      }]}
    ],
    description: '获取列车时刻表的信息',
    http: {path: '/timetable', verb: 'get', status: 200, errorStatus: 400}
  })