Implement getJsonSchemaRef and getModelSchemaRef helpers

[bajtos]

Introduce helpers for building JSON/OpenAPI schema referencing shared model definition.

// packages/repository-json-schema/src/build-schema.ts
export function getJsonSchemaRef(
  ctor: Function,
  options: JsonSchemaOptions = {},
): JSONSchema {
  const schemaWithDefinitions = getJsonSchema(ctor, options);
  const key = schemaWithDefinitions.title;

  // ctor is not a model
  if (!key) return schemaWithDefinitions;

  const definitions = Object.assign({}, schemaWithDefinitions.definitions);
  const schema = Object.assign({}, schemaWithDefinitions);
  delete schema.definitions;
  definitions[key] = schema;

  return {
    $ref: `#/definitions/${key}`,
    definitions,
  };
}

// packages/openapi-v3/src/controller-spec.ts
export function getModelSchemaRef(
  modelCtor: Function,
  options: JsonSchemaOptions,
) {
  const jsonSchema = getJsonSchemaRef(modelCtor, options);
  return jsonToSchemaObject(jsonSchema);
}

See the spike #2592 for more details.

This story requires us to implement Allow controllers to provide definitions of models referenced in operation spec #2629 first.

Acceptance criteria

• Implement the two new helpers described above
• Test coverage
• API documentation