docs: parameter shorthand example

README.md

@@ -6,11 +6,11 @@ Generate an OpenAPI/Swagger definition from inline comments.
 
 [![](https://d3vv6lp55qjaqc.cloudfront.net/items/1M3C3j0I0s0j3T362344/Untitled-2.png)](https://readme.io)
 
-* [Installation](#installation)
-* [Usage](#usage)
-  * [CLI](#cli)
-  * [Library](#library)
-* [Examples](#examples)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [CLI](#cli)
+  - [Library](#library)
+- [Examples](#examples)
 
 ## Installation
 
@@ -19,7 +19,9 @@ npm install swagger-inline --save-dev
 ```
 
 ## Usage
+
 ### CLI
+
 ```
 npx swagger-inline [--base] [--format] <inputGlobs ...>
 ```
@@ -31,9 +33,10 @@ npx swagger-inline "./*.js" --base 'swaggerBase.json' > api.json
 ```
 
 #### Options
+
 The `inputGlobs` argument is a list of files, or globs, to search for Swagger/OAS comments.
 
-- `base`: Base API specification to extend. ***Required**
+- `base`: Base API specification to extend. **\*Required**
 - `format`: Output filetype: `.json` or `.yaml` (default: `.json`)
 - `scope`: Matches the scope field defined in each API. For example, if `--scope public` is supplied, all operations will be generated, if `--scope private`, only those operations that have a `scope: private` declaration will be included.
 
@@ -50,13 +53,14 @@ const swaggerInline = require('swagger-inline');
 
 swaggerInline(['src/**/*.js', 'test/**/*.js'], {
   base: 'swaggerBase.json',
-}).then((generatedSwagger) => {
+}).then(generatedSwagger => {
   /* ... */
 });
 ```
 
 #### Available options
-- `base`: Base specification to extend. ***Required**
+
+- `base`: Base specification to extend. **\*Required**
 - `format`: Output filetype: `.json` or `.yaml` (default: `.json`)
 - `ignore`: An array of globs for files to ignore. (default: `['node_modules/**/*', 'bower_modules/**/*']`,
 - `logger`: Function called for logging. (default: empty closure)
@@ -65,22 +69,23 @@ swaggerInline(['src/**/*.js', 'test/**/*.js'], {
 - `ignoreErrors`: Ignore errors due to image files or unknown file types when parsing files. (default: `false`)
 
 ## Examples
+
 ### Standard usage
+
 #### 1) Create a project
 
 `swaggerBase.yaml`
 
 ```yaml
-swagger: "2.0"
-host: "petstore.swagger.io"
-basePath: "/api"
+swagger: '2.0'
+host: 'petstore.swagger.io'
+basePath: '/api'
 schemes: ['http']
- ```
+```
 
 `api.js`
 
 ```js
-
 /**
  * @api [get] /pets
  * bodyContentType: "application/json"
@@ -92,8 +97,8 @@ schemes: ['http']
  *       type: "String"
  */
 
-api.route('/pets', function() {
-    /* Pet code 😺 */
+api.route('/pets', function () {
+  /* Pet code 😺 */
 });
 
 /**
@@ -112,7 +117,6 @@ api.route('/pets', function() {
  */
 
 // some schema related function
-
 ```
 
 #### 2) Run Command
@@ -155,6 +159,7 @@ components:
 ```
 
 ### Scoped compilations
+
 With the `--scope` parameter, you can compile your files based on a specific target that you define within your inline comments. For example, we have an API with a `GET /pets` and `POST /pets` but only the `GET` operation is public. We can add `scope: public` to our `GET` operation documentation to tell `swagger-inline` what scope it's set under.
 
 ```js
@@ -176,6 +181,32 @@ With the `--scope` parameter, you can compile your files based on a specific tar
  *   "200":
  *     description: "The created pet."
  */
- ```
+```
 
 Now when you run `swagger-inline`, you can supply `--scope public` and only the `GET /pets` operation will be picked up. Omit `--scope public` and everything will be picked up.
+
+### Parameter shorthand declarations
+
+Defining a parameter in OpenAPI can be verbose, so you can define parameters via shorthands. If you require something more complex, you can use the [full OpenAPI parameter syntax](https://swagger.io/docs/specification/describing-parameters/).
+
+Here's a simple example:
+
+```
+(query) limit=5* {Integer:int32} Amount returned
+```
+
+It has a lot of info packed into a short space:
+
+- The parameter type: `query`
+- The name of the parameter: `limit`
+- The default value: 5
+- A flag to indicate that the parameter is required: `*`
+- The type: `Integer`
+- The format of the type: `int32`
+- The parameter description: `Amount returned`
+
+Almost all of these are optional — you can write something as concise as this:
+
+```
+(query) limit
+```