docs: openapi v3 decorators #1145

jannyHou · 2018-03-19T13:50:51Z

connect to #753

Checklist

npm test passes on your machine(running)
~~[ ] New tests added or existing tests modified to cover all changes~~
Code conforms with the style guide
Related API Documentation was updated
~~[ ] Affected artifact templates in packages/cli were updated~~
~~[ ] Affected example projects in packages/example-* were updated~~

bajtos · 2018-03-19T14:08:50Z

docs/site/Decorators.md

@@ -132,56 +132,181 @@ accordingly or do a composition of them:
  For more usage, refer to [Routing to Controllers](controllers.htm#routing-to-controllers)

 ### Parameter Decorator
+
+  Syntax: see [API document](https://github.com/strongloop/loopback-next/blob/master/packages/openapi-v3/src/parameter-decorator.ts#L18-L29)


Did you perhaps mean API documentation?

Also, could you please point to http://apidocs.loopback.io instead of TypeScript source?

If we decide to keep the link to a ts file, then please make sure the link points to a specific revision, not the master branch. Otherwise the link will point to wrong line numbers soon, as the code will evolve.

@bajtos oops a typo, there is a bug of ts doc parsing function:

Given a function and namespace with the same name, it only parses the namespace, but could not detect the function. That's why I point it to the code as a workaround.

Interesting...seems people have different opinions on the link's branch. I use "a specific version" before but Kevin corrected me to use master....personally I agree with "a specific version".

Appreciate more opinion from team @strongloop/lb-next-dev , for the code links in documentation, would you point them to master branch or a specific version?

It is often that the line numbers change over time, so I'd avoid pointing to the source code, no matter which branch it is pointing to. My question to you, @jannyHou, would be.. what do we want to show to the users that we cannot show in a more static document, like API docs?

@dhmlau My link points to the tsdoc of source code :( I agree that this is the last choice...while could not think of a better idea as workaround

bajtos · 2018-03-19T14:10:09Z

docs/site/Decorators.md

-  refer to [TypeScript Decorator Documentation](https://www.typescriptlang.org/docs/handbook/decorators.html)
+  You can find the specific usage in [Writing Controller methods](controller.htm#writing-controller-methods)
+
+  *We are supporting parameter location 'cookie' in the feature, track the feature in story*


The parameter location cookie is not supported yet, see #997.

shimks · 2018-03-19T14:48:34Z

docs/site/Decorators.md

  ```

-  or
+  Writing the whole parameter specification is tedious, we create shortcuts to define params with pattern `@param.${in}.${type}(${name})`:


... tedious, so we've created shortcuts to define the parameter with the pattern ...

shimks · 2018-03-19T14:49:28Z

docs/site/Decorators.md

-  or
+  Writing the whole parameter specification is tedious, we create shortcuts to define params with pattern `@param.${in}.${type}(${name})`:
+
+  - in: the parameter location, one of the following values: `query`, `header`, `path`.


... location. It can be one of the ...

shimks · 2018-03-19T14:50:51Z

docs/site/Decorators.md

+  Writing the whole parameter specification is tedious, we create shortcuts to define params with pattern `@param.${in}.${type}(${name})`:
+
+  - in: the parameter location, one of the following values: `query`, `header`, `path`.
+  - type: a [common name of OpenAPI primitive data type](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#data-types), 


The wording for this bullet point is a bit awkward. Could you rewrite it so that it's clearer what type is for?

@shimks could you elaborate more about which part confuses you?

I moved take specifying a data get from query.... to next paragraph, see if it improves :)

should it be the common name instead of a common name?

Also, is type the type of the parameter? If so, not sure if we need the type specifying a data...

shimks · 2018-03-19T14:52:08Z

docs/site/Decorators.md

+  - type: a [common name of OpenAPI primitive data type](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#data-types), 
+    take specifying a data get from query as an example, a list of available shortcuts can
+    be found in [API document](http://apidocs.loopback.io/@loopback%2fopenapi-v3/#param.query).
+  - name: name of the parameter, should be a `string`, 


... parameter. It should be a 'string'

shimks · 2018-03-19T14:52:35Z

docs/site/Decorators.md


+  An equivalent example using shortcut decorator would be:


... using the shortcut decorator ...

shimks · 2018-03-19T15:04:26Z

docs/site/Decorators.md

+  *About decorating models and the corresponding OpenAPI schema, please check*
+  *[model decorators](#model-decorators)*
+
+  Then a typical usage of `@requestBody` is specifying a parameter's type as the model class,


A typical usage of '@requestBody' is specifying a parameter as a requestBody by decorating it or something along that line.

@shimks I still prefer to keep "then" :)

There is some code snippet in between, but the context is:

When the decorated argument is a custom type or a model, we recommend you define a model class with @model and @property. Then a typical usage of @requestBody is specifying a parameter's type as the model class, and applying the decorator on it.

shimks · 2018-03-19T15:04:50Z

docs/site/Decorators.md

+  }
+  ```
+
+  For the simplest use case, you can leave the input of `@requestBody` empty, we automatically


... empty since we automatically ...

shimks · 2018-03-19T15:05:18Z

docs/site/Decorators.md

+  ```
+
+  For the simplest use case, you can leave the input of `@requestBody` empty, we automatically
+  detect the type of `user`, generate the corresponding schema for it. 


... type of 'users' and generate the ...

shimks · 2018-03-19T15:05:51Z

docs/site/Decorators.md

+
+  For the simplest use case, you can leave the input of `@requestBody` empty, we automatically
+  detect the type of `user`, generate the corresponding schema for it. 
+  And the default content type is set to be `application/json`.


The default content type ... (no And)

shimks · 2018-03-19T15:06:32Z

docs/site/Decorators.md


-  So an example would be `@param.query.number('offset')`.
-  You can find the specific usage in [Writing Controller methods](controller.md#writing-controller-methods)
+  *We are supporting more `@requestBody` shorts in the future, track the feature in story*


b-admike · 2018-03-19T14:42:15Z

docs/site/Decorators.md

-
-  `@param` can be applied to method itself or specific parameters, it describes
-  an input parameter of a Controller method.
+  `@param` is applied to method parameters to generate OpenAPI parameter specification for it.


it -> them

b-admike · 2018-03-19T14:42:55Z

docs/site/Decorators.md

-
-  `@param` can be applied to method itself or specific parameters, it describes
-  an input parameter of a Controller method.
+  `@param` is applied to method parameters to generate OpenAPI parameter specification for it.


Can we say controller method parameters to be more explicit?

section "parameter decorator" and "requestBody decorator" are under "Route decorators", which says they are for controllers. But true, the sections is far from their parent, I added keyword "controller" for both.

dhmlau · 2018-03-19T16:35:58Z

docs/site/Decorators.md

+  }
+  ```
+  *About decorating models and the corresponding OpenAPI schema, please check*
+  *[model decorators](#model-decorators)*


missing . for the end of the sentence.

shimks

Round 2 let's go

shimks · 2018-03-19T17:54:17Z

docs/site/Decorators.md

  ```

-  or
+  Writing the whole parameter specification is tedious, we've created shortcuts to define


... tedious, so we've ...

shimks · 2018-03-19T17:57:00Z

docs/site/Decorators.md

+  Writing the whole parameter specification is tedious, we've created shortcuts to define
+  the params with the pattern `@param.${in}.${type}(${name})`:
+
+  - in: the parameter location, it can be one of the following values: `query`, `header`, `path`.


I'm just going to list out incorrect usages of commas as COMMA for the rest of the review.

Commas can't be used to connect two separate thoughts; use either a semicolon (;)(if the sentences are similar enough in theme), a period (.), or reword the sentences so that they can be connected by commas.

COMMA

shimks · 2018-03-19T17:57:38Z

docs/site/Decorators.md

+
+  - in: the parameter location, it can be one of the following values: `query`, `header`, `path`.
+  - type: a [common name of OpenAPI primitive data type](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#data-types). 
+  - name: name of the parameter, it should be a `string`.


shimks · 2018-03-19T17:58:15Z

docs/site/Decorators.md

+  - type: a [common name of OpenAPI primitive data type](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#data-types). 
+  - name: name of the parameter, it should be a `string`.
+
+  Take specifying a data from query as an example, a list of available shortcuts for can


shimks · 2018-03-19T17:58:58Z

docs/site/Decorators.md

-  decorator must be applied after an operation decorator.
-  To learn more about TypeScript decorator composition,
-  refer to [TypeScript Decorator Documentation](https://www.typescriptlang.org/docs/handbook/decorators.html)
+  You can find the specific usage in [Writing Controller methods](controllers.md#writing-controller-methods)


You can find specific use cases in ...

Also, the link is still dead

@shimks I checked with Biniam, according to https://github.com/benbalter/jekyll-relative-links "controllers.md#writing-controller-methods" should be the correct format.
Do you have a valid example that I can look at?

Oh, the PR might not have been rebased, that could be why the link is dead. I'd just advise to test out all links before pushing it upstream

shimks · 2018-03-19T18:02:00Z

docs/site/Decorators.md

+  *To learn more about decorating models and the corresponding OpenAPI schema, please check*
+  *[model decorators](#model-decorators).*
+
+  Then a typical usage of `@requestBody` is specifying a parameter's type as the model class,


Grammatically, this sentence is incomplete. I expect a sentence listing out the condition using 'if' before the sentence using 'then'

I get what you're trying to say now with this section. Here's how I would word it based on the context you've given:

In order to use 'requestBody', the parameter type it's decorating needs to have its model decorated with '@model' and '@property' CODE EXAMPLE This allows type information of the model to be visible to the spec generator and '@requestBody' can finally be used on the parameter: CODE EXAMPLE

shimks · 2018-03-19T18:04:53Z

docs/site/Decorators.md

+
+  You can also customize the generated `requestBody` specification in 3 ways:
+
+  * add fields `description` and `required`


I'd like to see a more succinct organization of use cases of requestBody. Quoting from #1064 for inspiration:

single content-type

schema automatically generated with application/json with or without optional properties schema automatically generated with explicitly set content-type with or without optional properties schema set by user

@shimks Sorry I don't quite agree with you here, the simplest example and 3 customized scenarios covered the following use cases:

schema automatically generated with application/json with or without optional properties schema automatically generated with explicitly set content-type with or without optional properties schema set by user

IMO there are three items can be customized:

optional properties('description', 'required')

content type

schema spec

And that's how I classify the use cases.

shimks · 2018-03-19T18:08:01Z

docs/site/Decorators.md

+
+  *Only one parameter can be decorated by `@requestBody` per controller method.*
+
+  A typical OpenAPI requestBody spec contains properties `description`, `required`, and `content`:


Link here please https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#requestBodyObject

shimks · 2018-03-19T18:09:50Z

docs/site/Decorators.md

+  ```
+
+  For the simplest use case, you can leave the input of `@requestBody` empty, 
+  since we automatically detect the type of `user`, and generate the corresponding schema for it. 


no comma needed here

shimks · 2018-03-19T18:10:59Z

docs/site/Decorators.md

+  }
+  ```
+
+  For the simplest use case, you can leave the input of `@requestBody` empty, 


no comma between '@requestBody' empty and 'since we automatically'

shimks · 2018-03-19T19:10:53Z

docs/site/Decorators.md

+  - type: A [common name of OpenAPI primitive data type](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#data-types). 
+  - name: Name of the parameter. It should be a `string`.
+
+  Take specifying a data from query as an example, a list of available shortcuts for can


I guess I'm confused as to what this sentence is trying to say. Did you possibly mean to say Taking instead of Take?

For example, to specify data from a query, a list of available shortcuts can be found in [APIDocs](...)

shimks · 2018-03-19T19:12:53Z

docs/site/Decorators.md

-  decorator must be applied after an operation decorator.
-  To learn more about TypeScript decorator composition,
-  refer to [TypeScript Decorator Documentation](https://www.typescriptlang.org/docs/handbook/decorators.html)
+  You can find the specific usage in [Writing Controller methods](controllers.md#writing-controller-methods)


Oh, the PR might not have been rebased, that could be why the link is dead. I'd just advise to test out all links before pushing it upstream

shimks

🛎 ROUND 3 🛎

shimks · 2018-03-19T19:14:27Z

docs/site/Decorators.md

+  ```
+
+  For the simplest use case, you can leave the input of `@requestBody` empty
+  since we automatically detect the type of `user`, and generate the corresponding schema for it. 


shimks · 2018-03-19T19:35:02Z

docs/site/Decorators.md

+  *To learn more about decorating models and the corresponding OpenAPI schema, please check*
+  *[model decorators](#model-decorators).*
+
+  Then a typical usage of `@requestBody` is specifying a parameter's type as the model class,


I get what you're trying to say now with this section. Here's how I would word it based on the context you've given:

In order to use 'requestBody', the parameter type it's decorating needs to have its model decorated with '@model' and '@property' CODE EXAMPLE This allows type information of the model to be visible to the spec generator and '@requestBody' can finally be used on the parameter: CODE EXAMPLE

virkt25 · 2018-03-19T14:08:43Z

docs/site/Decorators.md

@@ -132,56 +132,181 @@ accordingly or do a composition of them:
  For more usage, refer to [Routing to Controllers](controllers.htm#routing-to-controllers)

 ### Parameter Decorator
+
+  Syntax: see [API document](https://github.com/strongloop/loopback-next/blob/master/packages/openapi-v3/src/parameter-decorator.ts#L18-L29)


Can we link to apidocs.loopback.io instead please as the line numbers may change over time.

sorry replying late, there is a bug in tsdoc so I have to take this workaround, details see discussion:
#1145 (comment)

@virkt25 BTW the fix for it is tracked in #584 (comment). I added a comment there to remind myself update doc after it's fixed.

virkt25 · 2018-03-19T19:47:53Z

docs/site/Decorators.md

@@ -132,56 +132,185 @@ accordingly or do a composition of them:
  For more usage, refer to [Routing to Controllers](controllers.htm#routing-to-controllers)

 ### Parameter Decorator
+
+  Syntax: see [API documentation](https://github.com/strongloop/loopback-next/blob/master/packages/openapi-v3/src/parameter-decorator.ts#L18-L29)


Can we link to apidocs.loopback.io instead since line number may change over time

virkt25 · 2018-03-19T19:49:22Z

docs/site/Decorators.md


-  Syntax: [`@param(paramSpec: ParameterObject)`]()
+  Shortcut Pattern: `@param.${in}.${type}(${name})`


I would revert this line since the Shortcut Patter is introduced later in Line 170

virkt25 · 2018-03-19T19:51:36Z

docs/site/Decorators.md

+  - type: A [common name of OpenAPI primitive data type](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#data-types). 
+  - name: Name of the parameter. It should be a `string`.
+
+  Take specifying a data from query as an example, a list of available shortcuts for can


For example, to specify data from a query, a list of available shortcuts can be found in [APIDocs](...)

virkt25 · 2018-03-19T19:53:11Z

docs/site/Decorators.md

-  Please note method level `@param` and parameter level `@param` are mutually exclusive,
-  you can not mix and apply them to the same parameter.
+  *The parameter location cookie is not supported yet, see*
+  *https://github.com/strongloop/loopback-next/issues/997*


You don't need to end with * on above line, it automatically carries the style over.

Please change the text for link to an actual link.

virkt25 · 2018-03-19T19:53:34Z

docs/site/Decorators.md

-  - in: one of the following values: `query`, `header`, `path`, `formData`, `body`
-  - type: one of the following values:  `string`, `number`, `boolean`, `integer`
-  - name: a `string`, name of the parameter
+  Syntax: see [API documentation](https://github.com/strongloop/loopback-next/blob/master/packages/openapi-v3/src/request-body-decorator.ts#L20-L79)


Link to apidocs.loopback.io instead of code

b-admike · 2018-03-28T13:11:38Z

docs/site/Decorators.md

+  }
+  ```
+
+  In order to use 'requestBody', the parameter type it's decorating needs to have its model decorated with '@model' and '@property'


nitpick: suggest to use backtick ` for @model and @Property instead of single quote.

good catch!

b-admike · 2018-03-28T13:14:47Z

docs/site/Decorators.md

+  ```ts
+  import {User} from '../models/user'
+  import {put} from '@loopback/rest'
+  // in file controller.ts


nitpick: suggest our convention of /src/controllers/user.controller.ts here

shimks · 2018-03-28T20:20:50Z

Is this the last of the task for #753? If it is, make sure to check it off in the milestone (#937)

jannyHou requested review from bajtos and raymondfeng as code owners March 19, 2018 13:50

jannyHou added the needs-priority label Mar 19, 2018

jannyHou force-pushed the v3/docs branch from a1caa69 to 6eb424e Compare March 19, 2018 13:59

bajtos reviewed Mar 19, 2018

View reviewed changes

shimks reviewed Mar 19, 2018

View reviewed changes

b-admike reviewed Mar 19, 2018

View reviewed changes

dhmlau reviewed Mar 19, 2018

View reviewed changes

jannyHou force-pushed the v3/docs branch from 8178155 to 0a529e0 Compare March 19, 2018 17:17

shimks suggested changes Mar 19, 2018

View reviewed changes

shimks reviewed Mar 19, 2018

View reviewed changes

virkt25 reviewed Mar 19, 2018

View reviewed changes

jannyHou force-pushed the v3/docs branch 3 times, most recently from b190bd2 to 5d02235 Compare March 27, 2018 17:54

jannyHou mentioned this pull request Mar 27, 2018

docs: Missing @param() decorator API Docs #584

Closed

jannyHou force-pushed the v3/docs branch 2 times, most recently from 1f3c66d to 24b9188 Compare March 27, 2018 20:22

shimks approved these changes Mar 27, 2018

View reviewed changes

virkt25 approved these changes Mar 27, 2018

View reviewed changes

b-admike approved these changes Mar 28, 2018

View reviewed changes

docs: openapi v3 decorators

960eaad

jannyHou force-pushed the v3/docs branch from 24b9188 to 960eaad Compare March 28, 2018 16:27

jannyHou merged commit ac518f1 into master Mar 28, 2018

jannyHou removed the needs-priority label Mar 28, 2018

jannyHou deleted the v3/docs branch May 17, 2018 21:17


		You can also customize the generated `requestBody` specification in 3 ways:

		* add fields `description` and `required`


		Only one parameter can be decorated by `@requestBody` per controller method.

		A typical OpenAPI requestBody spec contains properties `description`, `required`, and `content`:


		Syntax: [`@param(paramSpec: ParameterObject)`]()
		Shortcut Pattern: `@param.${in}.${type}(${name})`

docs: openapi v3 decorators #1145

docs: openapi v3 decorators #1145

Conversation

jannyHou commented Mar 19, 2018 • edited Loading

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dhmlau Mar 19, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou Mar 19, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shimks left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shimks left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shimks commented Mar 28, 2018

jannyHou commented Mar 19, 2018 •

edited

Loading

dhmlau Mar 19, 2018 •

edited

Loading

jannyHou Mar 19, 2018 •

edited

Loading