|
@@ -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:
|
|
|
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+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:**
|
|
|
-
|
|
|
-
|
|
|
+## 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>`.
|
|
|
|
|
|
-
|
|
|
+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"
|
|
|
-```
|
|
|
+
|
|
|
+
|
|
|
|
|
|
-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
|
|
|
-{
|
|
|
+```
|
|
|
|
|
|
-}
|
|
|
+
|
|
|
|
|
|
-// 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`.
|