Merge pull request #158 from apiaryio/pksunkara/parameters

Align parameters syntax with attributes

API Blueprint Specification.md

@@ -768,17 +768,19 @@ Defined by the `Parameters` keyword written in a Markdown list item:
 #### Description
 Discussion of URI parameters in the _scope of the parent section_.
 
-This section **must** be composed of nested list items only. This section **must not** contain any other elements. One list item per URI parameter. The nested list items subsections inherit from the [Named section](#def-named-section) and are subject to additional formatting as follows:
+This section **must** be composed of nested list items only. This section **must not** contain any other elements. Each list item describes a single URI parameter. The nested list items subsections inherit from the [Named section](#def-named-section) and are subject to additional formatting as follows:
 
-    + <parameter name> = `<default value>` (required | optional , <type>, `<example value>`) ... <description>
+    + <parameter name>: `<example value>` (<type> | enum[<type>], required | optional) - <description>
 
         <additional description>
 
-        + Values
-            + `<enumeration element 1>`
-            + `<enumeration element 2>`
+        + Default: `<default value>`
+
+        + Members
+            + `<enumeration value 1>` - <enumeration description 1>
+            + `<enumeration value 2>` - <enumeration description 2>
             ...
-            + `<enumeration element N>`
+            + `<enumeration value N>` - <enumeration description N>
 
 Where:
 
@@ -787,9 +789,10 @@ Where:
 * `<additional description>` is any additional **optional** Markdown-formatted [description](#SectionDescription) of the parameter.
 * `<default value>` is an **optional** default value of the parameter – a value that is used when no value is explicitly set (optional parameters only).
 * `<example value>` is an **optional** example value of the parameter (e.g. `1234`).
-* `<type>` is the **optional** parameter type as expected by the API (e.g. "number").
-* `Values` is the **optional** enumeration of possible values
-*  and `<enumeration element n>` represents an element of enumeration type.
+* `<type>` is the **optional** parameter type as expected by the API (e.g. "number", "string", "boolean"). "string" is the **default**.
+* `Members` is the **optional** enumeration of possible values. `<type>` should be surrounded by `enum[]` if this is present. For example, if enumeration values are present for a parameter whose type is `number`, then `enum[number]` should be used instead of `number` to.
+* `<enumeration value n>` represents an element of enumeration type.
+* `<enumeration description n>` is the **optional** description of the corresponding enumeration element.
 * `required` is the **optional** specifier of a required parameter (this is the **default**)
 * `optional` is the **optional** specifier of an optional parameter.
 
@@ -803,34 +806,35 @@ Where:
 
 ```
 + Parameters
-    + id ... Id of a post.
+    + id - Id of a post.
 ```
 
 ```
 + Parameters
-    + id (number) ... Id of a post.
+    + id (number) - Id of a post.
 ```
 
 ```
 + Parameters
-    + id (required, number, `1001`) ... Id of a post.
+    + id: `1001` (number, required) - Id of a post.
 ```
 
 ```
 + Parameters
-    + id = `20` (optional, number, `1001`) ... Id of a post.
+    + id: `1001` (number, optional) - Id of a post.
+        + Default: `20`
 ```
 
 ```
 + Parameters
-    + id (string)
+    + id (enum[string])
 
         Id of a Post
 
-        + Values
-            + `A`
+        + Members
+            + `A` - This is character A
             + `B`
-            + `C`
+            + `C` - This is character C
 ```
 ---
 

examples/07. Parameters.md

@@ -19,7 +19,7 @@ Note the parameter name `id` is enclosed in curly brackets. We will discuss this
 
 + Parameters
 
-    + id (number, `1`) ... An unique identifier of the message.
+    + id: 1 (number) - An unique identifier of the message.
 
 ### Retrieve a Message [GET]
 
@@ -79,7 +79,8 @@ We have added the query URI template parameter - `limit`. This parameter is used
 
 + Parameters
 
-    + limit = `20` (optional, number) ... The maximum number of results to return.
+    + limit (number, optional) - The maximum number of results to return.
+        + Default: `20`
 
 + Response 200 (application/json)
 

examples/09. Advanced Attributes.md

@@ -20,7 +20,7 @@ The `Create a Coupon` action also demonstrate the description of request attribu
 A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer.
 
 + Parameters
-    + id (string) 
+    + id (string)
 
         The ID of the desired coupon.
 
@@ -47,10 +47,12 @@ Retrieves the coupon with the given ID.
 Returns a list of your coupons.
 
 + Parameters
-    + limit = `10` (optional, number)
+    + limit (number, optional)
 
         A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
 
+        + Default: `10`
+
 + Response 200 (application/json)
     + Attributes (Coupons)
 

examples/10. Data Structures.md

@@ -16,7 +16,7 @@ Since a portion of the `Coupon` data structure is shared between the `Coupon` de
 A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer.
 
 + Parameters
-    + id (string) 
+    + id (string)
 
         The ID of the desired coupon.
 
@@ -38,10 +38,12 @@ Retrieves the coupon with the given ID.
 Returns a list of your coupons.
 
 + Parameters
-    + limit = `10` (optional, number)
+    + limit (number, optional)
 
         A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
 
+        + Default: `10`
+
 + Response 200 (application/json)
     + Attributes (Coupons)
 

examples/Gist Fox API + Auth.md

@@ -53,8 +53,8 @@ The Gist resource has the following attributes:
 The states *id* and *created_at* are assigned by the Gist Fox API at the moment of creation. 
 
 + Parameters
-    + id (string) ... ID of the Gist in the form of a hash.
-    + access_token (string, optional) ... Gist Fox API access token.
+    + id (string) - ID of the Gist in the form of a hash.
+    + access_token (string, optional) - Gist Fox API access token.
 
 + Model (application/hal+json)
 
@@ -138,7 +138,7 @@ In addition it **embeds** *Gist Resources* in the Gist Fox API.
 
 ### List All Gists [GET]
 + Parameters
-    + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.
+    + since (string, optional) - Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.
 
 + Response 200
 
@@ -150,7 +150,7 @@ To create a new Gist simply provide a JSON hash of the *description* and *conten
 This action requires an `access_token` with `gist_write` scope. 
 
 + Parameters
-    + access_token (string, optional) ... Gist Fox API access token.
+    + access_token (string, optional) - Gist Fox API access token.
 
 + Request (application/json)
 
@@ -171,8 +171,8 @@ The Star resource has the following attribute:
 + starred
 
 + Parameters
-    + id (string) ... ID of the gist in the form of a hash
-    + access_token (string, optional) ... Gist Fox API access token.    
+    + id (string) - ID of the gist in the form of a hash
+    + access_token (string, optional) - Gist Fox API access token.
 
 + Model (application/hal+json)
 

examples/Gist Fox API.md

@@ -53,7 +53,7 @@ The states *id* and *created_at* are assigned by the Gist Fox API at the moment
 
 
 + Parameters
-    + id (string) ... ID of the Gist in the form of a hash.
+    + id (string) - ID of the Gist in the form of a hash.
 
 + Model (application/hal+json)
 
@@ -138,7 +138,7 @@ In addition it **embeds** *Gist Resources* in the Gist Fox API.
 
 ### List All Gists [GET]
 + Parameters
-    + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.
+    + since (string, optional) - Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.
 
 + Response 200
 
@@ -168,7 +168,7 @@ The Star resource has the following attribute:
 
 + Parameters
 
-    + id (string) ... ID of the gist in the form of a hash
+    + id (string) - ID of the gist in the form of a hash
 
 + Model (application/hal+json)
 

examples/Real World API.md

@@ -13,7 +13,7 @@ This section groups App.net post resources.
 A Post is the other central object utilized by the App.net Stream API. It has rich text and annotations which comprise all of the content a users sees in their feed. Posts are closely tied to the follow graph...
 
 + Parameters
-    + post_id (string, `1`) ... The id of the Post.
+    + post_id: `1` (string) - The id of the Post.
 
 + Model (application/json)
 
@@ -127,7 +127,7 @@ Retrieves all posts.
 A User’s stars are visible to others, but they are not automatically added to your followers’ streams.
 
 + Parameters
-    + post_id (string, `1`) ... The id of the Post.
+    + post_id: `1` (string) - The id of the Post.
 
 ### Star a Post [POST]
 Save a given Post to the current User’s stars. This is just a “save” action, not a sharing action.