Enhance getJsonSchema to describe navigational properties

[bajtos]

Improve the code converting LoopBack Model definitions into JSON Schema documents to optionally describe navigational properties for relations defined by the model. The decision is controlled by a new option passed to modelToJsonSchema and
related methods.

// own properties only
const spec = getJsonSchema(Product);
// include navigational properties too
const spec = getJsonSchema(Product, {includeRelations: true});

Add a new property to all relation definitions. This property will signal whether the relations is targeting a single model instance (e.g. BelongsTo, HasOne) or an array of instances (e.g. HasMany).

 export interface RelationDefinitionBase {
   /**
    * The type of the relation, must be one of RelationType values.
    */
   type: RelationType;

+  /**
+   * True for relations targeting multiple instances (e.g. HasMany),
+   * false for relations with a single target (e.g. BelongsTo, HasOne).
+   * This property is need by OpenAPI/JSON Schema generator.
+   */
+  targetsMany: boolean;

   // ...
}

Add a new property to options object used by getJsonSchema and modelToJsonSchema:

 export interface JsonSchemaOptions {
+  includeRelations?: boolean;
   visited?: {[key: string]: JSONSchema};
 }

Modify the implementation of modelToJsonSchema to include navigational properties when includeRelations is set.

See the spike #2592 and especially the commits 2256435 for more details. Please note the commit shows changes before the review feedback was applied. You need to review the final pull request diff of the PoC before copying any code over.

This story requires us to fix handling of circular references first, see #2628.

Acceptance criteria

• Implement the changes described above
• Test coverage
• Update API documentation

[emonddr]

@raymondfeng mentioned that the includeRelations should have the freedom to accept an array of relation names as well. A boolean field of includeRelations would mean we accept all relations.

includeRelations : true // includes all relations 
includeRelations: false // does not include any relations 
includeRelations:['rel1','rel2'] // includes these relations only.

[bajtos]

mentioned that the includeRelations should have the freedom to accept an array of relation names as well. A boolean field of includeRelations would mean we accept all relations.

Makes sense. Maybe we can leave this out of the initial implementation and wait until there is user demand for this more complex variant?

[dhmlau]

@samarpanB, I just assigned this issue to you, since you've indicated your interest to contribute: #1352 (comment).

[samarpanB]

Okay @dhmlau. @bajtos, I am going to need your guidance on this. I’ll follow what you have mentioned in the description. I’ll submit in-progress PR as soon as I get to something, so that you can review and let me know if I am on right track. Also if you want to provide me some heads up, please let me know.

[bajtos]

@samarpanB I am happy to help, let me know if you run into any questions.