Update docs

docs/documenting-endpoint-body-parameters.md

@@ -1,103 +1,96 @@
-# Documenting parameters for an endpoint
-[IN PROGRESS]
+# Documenting body and file parameters for an endpoint
 
-## Specifying request parameters
-To specify a list of valid parameters your API route accepts, use the `@urlParam`, `@bodyParam` and `@queryParam` annotations.
-- The `@urlParam` annotation is used for describing parameters in your URl. For instance, in a Laravel route with this URL: "/post/{id}/{lang?}", you would use this annotation to describe the `id` and `lang` parameters. It takes the name of the parameter, an optional "required" label, and then its description.
-- The `@queryParam` annotation takes the name of the parameter, an optional "required" label, and then its description.
-- The `@bodyParam` annotation takes the name of the parameter, its type, an optional "required" label, and then its description. 
+## Specifying body parameters
+To describe query parameters for your endpoint, use the `@bodyParam` annotation on the method handling it.
 
-Examples:
+The `@bodyParam` annotation takes the name of the parameter, its type, an optional "required" label, and then its description. Valid types:
+- `int` / `integer`
+- `string`
+- `number` / `float`
+- `boolean`
+- `array`
+- `object`
+- `file` (see [Documenting File Uploads](#documenting-file-uploads) below)
+
+By default, Scribe will generate a random value for each parameter, to be used in the example requests and response calls. If you'd like to use a specific example value, you can do so by adding `Example: your-example-here` to the end of your description.
+
+You can also exclude a particular parameter from the generated examples by ending with `No-example` instead. This will also prevent the parameter from being sent along in response calls. The parameter will still be included in the text of the documentation.
+
+Here's an example:
 
 ```php
 /**
- * @urlParam id required The ID of the post.
- * @urlParam lang The language.
  * @bodyParam user_id int required The id of the user. Example: 9
  * @bodyParam room_id string The id of the room.
  * @bodyParam forever boolean Whether to ban the user forever. Example: false
- * @bodyParam another_one number Just need something here.
- * @bodyParam yet_another_param object required Some object params.
- * @bodyParam yet_another_param.name string required Subkey in the object param.
- * @bodyParam even_more_param array Some array params.
- * @bodyParam even_more_param.* float Subkey in the array param.
- * @bodyParam book.name string
- * @bodyParam book.author_id integer
- * @bodyParam book[pages_count] integer
- * @bodyParam ids.* integer
- * @bodyParam users.*.first_name string The first name of the user. Example: John
- * @bodyParam users.*.last_name string The last name of the user. Example: Doe
+ * @bodyParam another_one number This won't be added to the examples. No-example
  */
 public function createPost()
 {
     // ...
 }
+```
+
+The body parameters will be included in the generated documentation text and example requests:
 
+![](images/endpoint-bodyparams-1.png)
+
+
+You can also add the `@queryParam` and `@bodyParam` annotations to a `\Illuminate\Foundation\Http\FormRequest` subclass instead, if you are using one in your controller method
+
+```php
 /**
- * @queryParam sort Field to sort by
- * @queryParam page The page number to return
- * @queryParam fields required The fields to include
+ * @bodyParam title string The title of the post.
+ * @bodyParam body string required The content of the post.
  */
-public function listPosts()
+class CreatePostRequest extends \Illuminate\Foundation\Http\FormRequest
+{
+
+}
+
+// in your controller...
+public function createPost(CreatePostRequest $request)
 {
     // ...
 }
 ```
 
-They will be included in the generated documentation text and example requests.
-
-**Result:**
-
-![](./../body_params_1.png)
+## Handling array and object parameters
+Sometimes you have body parameters that are arrays ir ibjects. To handle them in `@bodyparam`, Scribe follows Laravel's convention:
+- For arrays: use `<name>.*`
+- For objects: use `<name>.<key>`.
 
-![](./../body_params_2.png)
+This means that, for an array of objects, you'd use `<name>.*.<key>`.
 
-### Example parameters
-For each parameter in your request, this package will generate a random value to be used in the example requests. If you'd like to specify an example value, you can do so by adding `Example: your-example` to the end of your description. For instance:
+You can also add a "parent" description if you like, by using `@bodyParam` with the type as "object" or "array".
 
 ```php
-    /**
-     * @queryParam location_id required The id of the location.
-     * @queryParam user_id required The id of the user. Example: me
-     * @queryParam page required The page number. Example: 4
-     * @bodyParam user_id int required The id of the user. Example: 9
-     * @bodyParam room_id string The id of the room.
-     * @bodyParam forever boolean Whether to ban the user forever. Example: false
-     */
+/**
+ * @bodyParam user object required The user details
+ * @bodyParam user.name string required The user's name
+ * @bodyParam user.age string required The user's age
+ * @bodyParam friend_ids array List of the user's friends.
+ * @bodyParam friend_ids.* int User's friends.
+ * @bodyParam cars.*.year string The year the car was made. Example: 1997
+ * @bodyParam cars.*.make string The make of the car. Example: Toyota
+ */
 ```
 
-You can also exclude a particular parameter from the generated examples (for all languages) by annotating it with `No-example`. For instance:
-```php
-    /**
-    * @queryParam location_id required The id of the location. Example: 1
-    * @queryParam user_id required The id of the user. No-example
-    * @queryParam page required The page number. Example: 4
-    */
-```
-Outputs: 
-```bash
-curl -X GET -G "https://example.com/api?location_id=1&page=4"
-```
+![](images/endpoint-bodyparams-2.png)
+
 
-Note: You can also add the `@queryParam` and `@bodyParam` annotations to a `\Illuminate\Foundation\Http\FormRequest` subclass instead, if you are using one in your controller method
+## Documenting file uploads
+You can document file inputs by using `@bodyParam` with a type `file`. You can add a description and example as usual. 
+
+For files, your example should be the absolute path to a file that exists on your machine. If you don't specify an example, Scribe will generate a fake file for example requests and response calls.
 
 ```php
 /**
- * @queryParam user_id required The id of the user. Example: me
- * @bodyParam title string required The title of the post.
- * @bodyParam body string required The content of the post.
- * @bodyParam type string The type of post to create. Defaults to 'textophonious'.
- * @bodyParam author_id int the ID of the author. Example: 2
- * @bodyParam thumbnail image This is required if the post type is 'imagelicious'.
+ * @bodyParam caption string The image caption
+ * @bodyParam image required file The image.
  */
-class MyRequest extends \Illuminate\Foundation\Http\FormRequest
-{
+```
 
-}
+![](images/endpoint-bodyparams-3.png) 
 
-// in your controller...
-public function createPost(MyRequest $request)
-{
-    // ...
-}
-```
+> Note: Adding a file parameter will automatically set the 'Content-Type' header in example requests and response calls to `multipart/form-data`.

docs/documenting-endpoint-query-parameters.md

@@ -1,11 +1,11 @@
-# Documenting parameters for an endpoint
+# Documenting query and URL parameters for an endpoint
 
 ## Specifying query parameters
-To describe query parameters for your endpoint, use the `@queryParam` annotation.
+To describe query parameters for your endpoint, use the `@queryParam` annotation on the method handling it.
 
 The `@queryParam` annotation takes the name of the parameter, an optional "required" label, and a description.
 
-Examples:
+Here's an example:
 
 ```php
 /**
@@ -20,7 +20,7 @@ public function listPosts()
 }
 ```
 
-They will be included in the generated documentation text and example requests:
+The query parameters will be included in the generated documentation text and example requests:
 
 ![](images/endpoint-queryparams-1.png)
 
@@ -31,24 +31,24 @@ If you're using a FormRequwst in your controller, you can also add the `@queryPa
 
 ```php
 /**
- * @queryParam user_id required The id of the user. Example: me
+ * @queryParam user_id required The id of the user.
  */
-class MyRequest extends \Illuminate\Foundation\Http\FormRequest
+class CreatePostRequest extends \Illuminate\Foundation\Http\FormRequest
 {
 
 }
 
 // in your controller...
-public function createPost(MyRequest $request)
+public function createPost(CreatePostRequest $request)
 {
     // ...
 }
 ```
 
 ## Specifying example values
-By default, Scribe will generate a random value for each parameter to be used in the example requests and response calls. If you'd like to use a specific example value, you can do so by adding `Example: your-example` to the end of your description.
+By default, Scribe will generate a random value for each parameter, to be used in the example requests and response calls. If you'd like to use a specific example value, you can do so by adding `Example: your-example-here` to the end of your description.
 
-You can also exclude a particular parameter from the generated examples by ending with `No-example` instead. This will also prevent the parameter from being sent along in response calls.
+You can also exclude a particular parameter from the generated examples by ending with `No-example` instead. This will also prevent the parameter from being sent along in response calls. The parameter will still be included in the text of the documentation.
 
 For instance:
 

docs/documenting-endpoint-responses.md

@@ -1,5 +1,4 @@
-
-# Documenting endpoint responses
+# Documenting responses from an endpoint
 [IN PROGRESS]
 
 ## Providing an example response

docs/whats-new.md

@@ -15,7 +15,7 @@ Scribe can now add authentication information to your docs! The info you provide
  Also, you can describe multiple responses with the same (or different) status code, but applying to different scenarios. Check it out [here]().
 
 ## More customization options
-You can now customise the introductory text shown at the start of your documentation🙌. Full Markdown and HTML support, plus some nice little CSS classes to make things pretty. If you want to go even deeper and modify the output templates, we have some nice Blade components you can use. See [the docs]() for details.
+You can now customise the documentation title and the introductory text shown at the start of your documentation🙌. Full Markdown and HTML support, plus some nice little CSS classes to make things pretty. If you want to go even deeper and modify the output templates, we have some nice Blade components you can use. See [the docs]() for details.
 
 ## FormRequest support is back!🎉🎉🎉
 Yes, you've wanted it for a long time, and it's back.😄 We thought long and hard about how we could leverage what the framework gives to make devs' lives easier, and we realized that even though FormRequests are for validation, not documentation, they still contain useful business logic we can extract. So we decided to bring this back (with some conditions, though👀), and we're exploring ways to support other validation approaches. [Head over to the docs]() to know what you need to do to leverage this.