Custom schema title for POST requests #3716

bajtos · 2019-09-12T09:21:25Z

While reviewing #3698, #3504 and #1466, it occurred to me that schema titles like TodoExcluding[id] or ProductPartialExcluding[id,_rev] are not very friendly to human consumers.

In this pull request, I am introducing a new JsonSchemaOption title that allows developer to specify a title that described the intent (data of a new Todo to be created - NewTodo) instead of the implementation details (Todo data excluding id property).

The second commit updates controller templates and rest-crud package to leverage this new schema option for POST requests.

/cc @ericzon @remkohdev

IMPORTANT: Although this change is very likely to fix the issues described in #3698, #3504 and #1466 for newly created controllers, it's not meant as a replacement for #3504. I'd like #3504 to be landed, because it solves the problems for existing applications and users that decide to not use the title option for whatever reasons.

Checklist

👉 Read and sign the CLA (Contributor License Agreement) 👈

npm test passes on your machine
New tests added or existing tests modified to cover all changes
Code conforms with the style guide
API Documentation in code was updated
Documentation in /docs/site was updated
Affected artifact templates in packages/cli were updated
Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

bajtos · 2019-09-12T09:25:48Z

Discussion point:

The auto-generated titles add a suffix to the model name, e.g. TodoPartial, TodoWithRelations.
In this PR, I am using a prefix for the schema describing payload of a new model instance, e.g. NewTodo, because NewTodo looks better to me than TodoNew.

This introduces a small inconsistency in schema titles. Do we mind?

Please:

Upvote (👍) this comment if you agree with NewTodo.
Downvote (👎 ) this comment if you prefer TodoNew for consistency.

/cc @strongloop/loopback-next

hacksparrow · 2019-09-12T09:33:40Z

NewTodo should be made the new consistency standard, if it is not already.

Where is TodoNew used? I couldn't find any instance.

bajtos · 2019-09-12T09:41:11Z

Thank you @hacksparrow for the comment.

NewTodo should be made the new consistency standard, if it is not already.

Where is TodoNew used? I couldn't find any instance.

TodoNew is not used anywhere yet, but we are using TodoPartial and TodoWithRelations for PATCH and GET operations. (The titles TodoPartial and TodoWithRelations are auto-generated, you can view them when you run e.g. examples/todo and open the API Explorer.)

I see two options now:

NewTodo for POST, but TodoPartial for PATCH - this is the current implementation in my PR
TodoNew for POST and TodoPartial for PATCH - this is the other option, one that's more consistent IMO

hacksparrow · 2019-09-12T10:00:31Z

I don't feel any inconsistency in NewTodo vs. TodoPartial and TodoWithRelations.

I understand TodoPartial as (ExistingTodo)Partial, and TodoWithRelations as (ExistingTodo)WithRelations.

agnes512

Mostly look good to me, just a few comments.

agnes512 · 2019-09-12T12:47:31Z

packages/repository-json-schema/src/__tests__/integration/build-schema.integration.ts

+      }
+
+      const schema = getJsonSchema(TestModel, {
+        title: 'NewTestModel',


IIUC, the default format for the schema title is New+ModelName. And if we don't specified the title, it would be NewTestModel in this case.
The title of this test is uses custom title when provided by user. It replaces the title from IgnoredTitle to 'custom title' NewTestModel. But IgnoredTitle looks more like a custom title to me in this case.
Is it possible to change it to make the intention more clear?

@agnes512 Good point!

Let me clarify: The default format for the schema title would be IgnoredTitleExcluding['id'].

IgnoredTitle comes from the model-level setting, see https://github.com/strongloop/loopback-next/blob/5bebb5b41e6ce47fcfe7b2b84428b5c7acf3ef64/packages/repository-json-schema/src/build-schema.ts#L289

Excluding['id'] is the suffix based on options.exclude, see https://github.com/strongloop/loopback-next/blob/5bebb5b41e6ce47fcfe7b2b84428b5c7acf3ef64/packages/repository-json-schema/src/build-schema.ts#L300-L302

Model-level title setting IgnoredTitle applies to all calls of getJsonSchema where no options.title is provided. In my use case, I want to provide a different title in each getJsonSchema call.

Maybe I should rework this test into two? One verifying that model-level title is ignored, another verifying that suffix computed from options is ignored too?

What else can I do to make the intention more clear? If it's enough to improve the test name, could you please suggest a better one?

Thanks! 🙇

Good discussion here 👏

Some personal suggestion: maybe split it into two test cases like:

title in decorator > title inferred from model class name: verify the title in @model() overrides the title inferred from model class name. no options involved in this test.

title in options > title in decorator: verify the title in options overrides the title in @model(). And obviously option also overrides the one inferred from the model class(proved by the 1st test)

As a summary:
title in options > title in decorator > title inferred from model class name

Janny's suggestion looks good to me.

Done in 3d3e79b.

While improving the tests, I modified my new tests to call modelToJsonSchema instead of getJsonSchema, because they are not relying on caching behavior of getJsonSchema.

dhmlau · 2019-09-12T14:59:55Z

@bajtos, for consistency's sake, I think it might be better to have TodoNew rather than NewTodo. But I don't have a strong preference on that. Both options are better than the current title. :)

nabdelgadir · 2019-09-12T15:15:50Z

@bajtos so just to confirm, if the user chooses to use this title option, then the schema options will be available through the description after #3504 is landed?

And I agree with @hacksparrow's point; it feels as though the beginning part is describing whether it's New or Existing and the following part is the description of model schema options.

bajtos · 2019-09-12T15:38:40Z

So just to confirm, if the user chooses to use this title option, then the schema options will be available through the description after #3504 is landed?

Yes, that's my intention 👍

And I agree with @hacksparrow's point; it feels as though the beginning part is describing whether it's New or Existing and the following part is the description of model schema options.

That's a great way how to explain the schema naming convention 👍

packages/repository-json-schema/src/build-schema.ts

jannyHou

The change in PR looks reasonable to me, I left my understanding and suggestion in https://github.com/strongloop/loopback-next/pull/3716/files#r323856015, I feel it would be good to document how title from different places take precedence over each other :)

bajtos · 2019-09-13T07:54:17Z

I have realized that my original implementation had a flaw in the way how the schema is cached. I added 84db706 to fix it.

@jannyHou @agnes512 @nabdelgadir LGTY now?

agnes512

👍

nabdelgadir

LGTM 👍

packages/cli/generators/relation/templates/controller-relation-template-has-many.ts.ejs

jannyHou

👏 cool

Signed-off-by: Miroslav Bajtoš <mbajtoss@gmail.com>

…st bodies Signed-off-by: Miroslav Bajtoš <mbajtoss@gmail.com>

bajtos requested review from raymondfeng, samarpanB, nabdelgadir and a team September 12, 2019 09:21

bajtos self-assigned this Sep 12, 2019

agnes512 reviewed Sep 12, 2019

View reviewed changes

jannyHou reviewed Sep 12, 2019

View reviewed changes

packages/repository-json-schema/src/build-schema.ts Show resolved Hide resolved

jannyHou reviewed Sep 12, 2019

View reviewed changes

agnes512 approved these changes Sep 13, 2019

View reviewed changes

nabdelgadir approved these changes Sep 13, 2019

View reviewed changes

packages/cli/generators/relation/templates/controller-relation-template-has-many.ts.ejs Show resolved Hide resolved

jannyHou approved these changes Sep 13, 2019

View reviewed changes

bajtos added 2 commits September 16, 2019 09:58

feat(repository-json-schema): introduce new option "title"

99f3d79

Signed-off-by: Miroslav Bajtoš <mbajtoss@gmail.com>

feat: use descriptive title to describe schema of POST (create) reque…

31ddb95

…st bodies Signed-off-by: Miroslav Bajtoš <mbajtoss@gmail.com>

bajtos force-pushed the feat/custom-schema-title branch from 84db706 to 31ddb95 Compare September 16, 2019 07:58

bajtos merged commit 8f49a45 into master Sep 16, 2019

bajtos deleted the feat/custom-schema-title branch September 16, 2019 08:16

This was referenced Sep 16, 2019

Clean up tests for "lb4 relation" command #3748

Merged

fix(cli): fix schema title for POST operation in relation controllers #3754

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Custom schema title for POST requests #3716

Custom schema title for POST requests #3716

bajtos commented Sep 12, 2019

bajtos commented Sep 12, 2019

hacksparrow commented Sep 12, 2019

bajtos commented Sep 12, 2019

hacksparrow commented Sep 12, 2019

agnes512 left a comment

agnes512 Sep 12, 2019 •

edited

bajtos Sep 12, 2019 •

edited

jannyHou Sep 12, 2019 •

edited

agnes512 Sep 13, 2019

bajtos Sep 13, 2019

dhmlau commented Sep 12, 2019

nabdelgadir commented Sep 12, 2019

bajtos commented Sep 12, 2019

jannyHou left a comment

bajtos commented Sep 13, 2019

agnes512 left a comment

nabdelgadir left a comment

jannyHou left a comment

Custom schema title for POST requests #3716

Custom schema title for POST requests #3716

Conversation

bajtos commented Sep 12, 2019

Checklist

bajtos commented Sep 12, 2019

hacksparrow commented Sep 12, 2019

bajtos commented Sep 12, 2019

hacksparrow commented Sep 12, 2019

agnes512 left a comment

Choose a reason for hiding this comment

agnes512 Sep 12, 2019 • edited

Choose a reason for hiding this comment

bajtos Sep 12, 2019 • edited

Choose a reason for hiding this comment

jannyHou Sep 12, 2019 • edited

Choose a reason for hiding this comment

agnes512 Sep 13, 2019

Choose a reason for hiding this comment

bajtos Sep 13, 2019

Choose a reason for hiding this comment

dhmlau commented Sep 12, 2019

nabdelgadir commented Sep 12, 2019

bajtos commented Sep 12, 2019

jannyHou left a comment

Choose a reason for hiding this comment

bajtos commented Sep 13, 2019

agnes512 left a comment

Choose a reason for hiding this comment

nabdelgadir left a comment

Choose a reason for hiding this comment

jannyHou left a comment

Choose a reason for hiding this comment

agnes512 Sep 12, 2019 •

edited

bajtos Sep 12, 2019 •

edited

jannyHou Sep 12, 2019 •

edited