Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update decorator documentation for url-encoded query params #4621

Merged
merged 1 commit into from
Feb 13, 2020
Merged

docs: update decorator documentation for url-encoded query params #4621

merged 1 commit into from
Feb 13, 2020

Conversation

deepakrkris
Copy link
Contributor

@deepakrkris deepakrkris commented Feb 11, 2020 •
edited
Loading

issue: #2208

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 👈

@deepakrkris deepakrkris requested a review from bajtos February 11, 2020 06:43
@deepakrkris deepakrkris assigned jannyHou and unassigned jannyHou Feb 11, 2020
@deepakrkris deepakrkris requested a review from jannyHou February 11, 2020 06:44
dhmlau
dhmlau reviewed Feb 11, 2020
View reviewed changes
Copy link
Member

@dhmlau dhmlau left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please see my grammar related comments and incorporated as you find appropriate. Thanks.

docs/site/decorators/Decorators_openapi.md Outdated
One of the parameter decorator types, `@param.query.object` is applied to
generate an OpenAPI definition for query parameters with JSON values.

The generated definition supports the `url-encoded` style specified in Open-API.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open-API -> OpenAPI ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed

docs/site/decorators/Decorators_openapi.md Outdated
The generated definition supports the `url-encoded` style specified in Open-API.
This style supports receiving url-encoded payload for json query parameters.

For instance, to filter api results from the GET '/todo-list' endpoint in the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment in #4620, maybe just to filter the results... (without api) ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed

docs/site/decorators/Decorators_openapi.md Outdated
// filter={where: {completed: 'false'}}
```

LoopBack has switched definition of json query params from the `exploded`,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change:
LoopBack has switched the definition

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed

docs/site/decorators/Decorators_openapi.md Outdated

LoopBack has switched definition of json query params from the `exploded`,
`deep-object` style to the `url-encoded` style definition in Open-API spec, in a
recent release.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in a recent release.

This may not be relevant because the "recent" release may become not that recent soon. :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we can add a note like:

{% include note.html content="
LoopBack has switched definition of json query params from the .....
" %}

docs/site/decorators/Decorators_openapi.md Outdated
```

LoopBack has switched definition of json query params from the `exploded`,
`deep-object` style to the `url-encoded` style definition in Open-API spec, in a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open-API -> OpenAPI

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed

jannyHou
jannyHou reviewed Feb 12, 2020
View reviewed changes
docs/site/decorators/Decorators_openapi.md Outdated
// filter={where: {completed: 'false'}}
```

LoopBack has switched the definition of json query params from the `exploded`,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you move this sentence to the beginning of this section?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed

jannyHou
jannyHou reviewed Feb 12, 2020
View reviewed changes
docs/site/decorators/Decorators_openapi.md Outdated
One of the parameter decorator types, `@param.query.object` is applied to
generate an OpenAPI definition for query parameters with JSON values.

The generated definition supports the `url-encoded` style specified in Open API.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

supports the url-encoded style specified in OpenAPI.

Could you explain more about what does "url-encoded style specified in OpenAPI mean"? IIUC that style describes the syntax of an URL, but has nothing to do with OpenAPI spec.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agreed, Open API does not openly state an url-encoded style , but it defines a certain specification that allows url-encoded payload for query params. I will explain more about this.

@deepakrkris deepakrkris force-pushed the docs2208 branch 2 times, most recently from 838ba21 to 30f185f Compare February 12, 2020 19:40
nabdelgadir
nabdelgadir approved these changes Feb 13, 2020
View reviewed changes
docs/site/decorators/Decorators_openapi.md Outdated Show resolved Hide resolved
docs/site/decorators/Decorators_openapi.md Outdated Show resolved Hide resolved
@deepakrkris deepakrkris merged commit 1a386ac into master Feb 13, 2020
@deepakrkris deepakrkris deleted the docs2208 branch February 13, 2020 08:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@dhmlau dhmlau dhmlau left review comments

@agnes512 agnes512 agnes512 left review comments

@emonddr emonddr emonddr approved these changes

@jannyHou jannyHou jannyHou approved these changes

@nabdelgadir nabdelgadir nabdelgadir approved these changes

@bajtos bajtos Awaiting requested review from bajtos

Assignees
No one assigned
Labels
Docs OpenAPI
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
6 participants
@deepakrkris @emonddr @jannyHou @dhmlau @nabdelgadir @agnes512