Generate OpenAPI schema for Model properties of built-in JavaScript/Node.js types

[jannyHou]

cc @dhmlau

Description / Steps to reproduce / Feature proposal

import {model, property, DateType, Entity} from '@loopback/repository';

@model()
class Test extends Entity {
  @property()
  date: DateType
};

Current Behaviour

Since DateType is not a class decorated by @model, the generated OpenAPI spec doesn't generate schema for it in components.schemas

Expected Behaviour

automatically generate a schema entry in components.schemas for it.

Some proposal:

• Discovering datatype and generating schema/definition could happen when generate jsonDef or oai3Spec, which one is better?

Acceptance Criteria:

• For a model property in Loopback type(would be the types in @loopback/types), we automatically generate the openapi spec for it.

• For example:

// Given a class with properties in Loopback types
@model
class Test {
  @property
  date: Date
  @property
  text: Buffer
}

// The generated schema for model Test should be
{
  schemas: {
    Test: {
      type: 'object',
      properties: {
        date: {type: 'string', format: 'date'},
        text: {type: 'string', format: 'buffer'}
      }
    }
  }
}

• For each Loopback type, we can either map it to a simple schema like

schema: {type: string, format: 'date'}

or a schema reference

components: {
  schemas: {
    Date: {type: string, format: 'date'}
  }
}

People who works on this story can decide per type which approach is better. Types in scope:

• date
• boolean
• number
• string

Nice to have:

• DateTime (the class defined in juggler)
• buffer
• object
• GeoPoint
• ObjectID
• any model

[shimks]

I want to say this is covered by #1306. What do you think @jannyHou ?

[jannyHou]

@shimks I think this issue is the conversion from model class to openapi spec, while #1306 is for the conversion from request to controller method's input, so they are different things.

[shimks]

Personally, I see Date as something that LoopBack should convert from what's been given as a string (see https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14). How do you feel?

[jannyHou]

@shimks I updated the acceptance criteria in #1112 (comment), hope it clarifies the use case need to fix in this story.
I feel you still misunderstand the use case here, this story has nothing to do with request/response/coercion, it's all about fixing the generated OAI3 schema for a given model, it's not related to a run-time http request...

[shimks]

I understand that Date schema is missing, what I'm saying is that we may not need one anymore considering we're allowing the users to pass in an instance of Date as a string. Maybe we should still provide a schema for it if we want to allow the users to provide Date as an object. Thoughts @strongloop/sq-lb-apex, @raymondfeng, @bajtos?

[bajtos]

My opinion: If a remote method expects a date string in the input arguments, then the OpenAPI spec schema produced by LoopBack should clearly say so (so that clients understand what kind of a string to provide) and our REST layer should convert and validate the input value from string to a Date instance.

[jannyHou]

The description doesn't contain background info for people who's new to the rest decorators. FYI, here is a blog depicts how the OpenAPI concept is applied in LB4:
https://strongloop.com/strongblog/upgrade-from-swagger-to-openapi-3/

And also a list of related packages:

• @loopback/openapi-v3
• @loopback/openapi-v3-types
• @loopback/openapi-spec-builder
• @loopback/rest

[hacksparrow]

Fixed in #1731