Update documentation

README.md

@@ -17,7 +17,7 @@ Automatically generate your API documentation from your existing Laravel/Lumen/[
 > Note: PHP 7 and Laravel 5.5 or higher are required.
 
 ```sh
-$ composer require mpociot/laravel-apidoc-generator
+composer require mpociot/laravel-apidoc-generator
 ```
 
 ### Laravel
@@ -26,411 +26,25 @@ Publish the config file by running:
 ```bash
 php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config
 ```
+
 This will create an `apidoc.php` file in your `config` folder.
 
 ### Lumen
 - Register the service provider in your `bootstrap/app.php`:
-```php
-$app->register(\Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class);
-```
-- Copy the config file from `vendor/mpociot/laravel-apidoc-generator/config/apidoc.php` to your project as `config/apidoc.php`. Then add to your `bootstrap/app.php`:
-```php
-$app->configure('apidoc');
-```
-
-
-## Usage
-Before you can generate your documentation, you'll need to configure a few things in your `config/apidoc.php`.
-- `output`
-This is the file path where the generated documentation will be written to. Default: **public/docs**
-
-- `postman`
-This package can automatically generate a Postman collection for your routes, along with the documentation. This section is where you can configure (or disable) that.
-
-- `router`
-The router to use when processing the route (can be Laravel or Dingo. Defaults to **Laravel**)
-
-- `logo`
-You can specify your custom logo to be used on the generated documentation. Set the `logo` option to an absolute path pointing to your logo file.
-
-- `routes`
-This is where you specify what rules documentation should be generated for. You specify routes to be parsed by defining conditions that the routes should meet and rules that should be applied when generating documentation. These conditions and rules are specified in groups, allowing you to apply different rules to different routes.
-
-For instance, suppose your configuration looks like this:
 
 ```php
-return [
-     //...,
-  
-     'routes' => [
-          [
-              'match' => [
-                  'domains' => ['*'],
-                  'prefixes' => ['api/*', 'v2-api/*'],
-                  'versions' => ['v1'],
-              ],
-              'include' => ['users.index', 'healthcheck*'],
-              'exclude' => ['users.create', 'admin.*'],
-              'apply' => [
-                  'headers' => [
-                      'Authorization' => 'Bearer: {token}',
-                  ],
-              ],
-          ],
-];
-```
-
-This means documentation will be generated for routes in all domains ('*' is a wildcard meaning 'any character') which match any of the patterns 'api/*' or 'v2-api/*', excluding the 'users.create' route and any routes whose names begin with `admin.`, and including the 'users.index' route and any routes whose names begin with `healthcheck.`. (The `versions` key is ignored unless you are using Dingo router).
-Also, in the generated documentation, these routes will have the header 'Authorization: Bearer: {token}' added to the example requests.
-
-You can also separate routes into groups to apply different rules to them:
-
-```php
-<?php
-return [
-     //...,
-  
-     'routes' => [
-          [
-              'match' => [
-                  'domains' => ['v1.*'],
-                  'prefixes' => ['*'],
-              ],
-              'include' => [],
-              'exclude' => [],
-              'apply' => [
-                  'headers' => [
-                      'Token' => '{token}',
-                      'Version' => 'v1',
-                  ],
-              ],
-          ],
-          [
-              'match' => [
-                  'domains' => ['v2.*'],
-                  'prefixes' => ['*'],
-              ],
-              'include' => [],
-              'exclude' => [],
-              'apply' => [
-                  'headers' => [
-                      'Authorization' => 'Bearer: {token}',
-                      'Api-Version' => 'v2',
-                  ],
-              ],
-          ],
-];
-```
-
-With the configuration above, routes on the `v1.*` domain will have the `Token` and `Version` headers applied, while routes on the `v2.*` domain will have the `Authorization` and `Api-Version` headers applied.
-
-> Note: the `include` and `exclude` items are arrays of route names. THe &ast; wildcard is supported.
-> Note: If you're using Dingo router, the `versions` parameter is required in each route group. This parameter does not support wildcards. Each version must be listed explicitly,
-
-To generate your API documentation, use the `apidoc:generate` artisan command.
-
-```sh
-$ php artisan apidoc:generate
-
-```
-
-It will generate documentation using your specified configuration.
-
-## Documenting your API
-
-This package uses these resources to generate the API documentation:
-
-### Grouping endpoints
-
-This package uses the HTTP controller doc blocks to create a table of contents and show descriptions for your API methods.
-
-Using `@group` in a controller doc block creates a Group within the API documentation. All routes handled by that controller will be grouped under this group in the sidebar. The short description after the `@group` should be unique to allow anchor tags to navigate to this section. A longer description can be included below. Custom formatting and `<aside>` tags are also supported. (see the [Documentarian docs](http://marcelpociot.de/documentarian/installation/markdown_syntax))
-
- > Note: using `@group` is optional. Ungrouped routes will be placed in a "general" group.
-
-Above each method within the controller you wish to include in your API documentation you should have a doc block. This should include a unique short description as the first entry. An optional second entry can be added with further information. Both descriptions will appear in the API documentation in a different format as shown below.
-You can also specify an `@group` on a single method to override the group defined at the controller level.
-
-```php
-/**
- * @group User management
- *
- * APIs for managing users
- */
-class UserController extends Controller
-{
-
-	/**
-	 * Create a user
-	 *
-	 * [Insert optional longer description of the API endpoint here.]
-	 *
-	 */
-	 public function createUser()
-	 {
-
-	 }
-	 
-	/**
-	 * @group Account management
-	 *
-	 */
-	 public function changePassword()
-	 {
-
-	 }
-}
-```
-
-**Result:** 
-
-![Doc block result](http://headsquaredsoftware.co.uk/images/api_generator_docblock.png)
-
-### Specifying request parameters
-
-To specify a list of valid parameters your API route accepts, use the `@bodyParam` and `@queryParam` annotations.
-- The `@bodyParam` annotation takes the name of the parameter, its type, 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
-
-
-```php
-/**
- * @bodyParam title string required The title of the post.
- * @bodyParam body string required The title of the post.
- * @bodyParam type string The type of post to create. Defaults to 'textophonious'.
- * @bodyParam author_id int the ID of the author
- * @bodyParam thumbnail image This is required if the post type is 'imagelicious'.
- */
-public function createPost()
-{
-    // ...
-}
-
-/**
- * @queryParam sort Field to sort by
- * @queryParam page The page number to return
- * @queryParam fields required The fields to include
- */
-public function listPosts()
-{
-    // ...
-}
-```
-
-They will be included in the generated documentation text and example requests.
-
-**Result:**
-
-![](body_params.png)
-
-Note: a random value will be used as the value of each parameter 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:
-
-```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
-     */
-```
-
-Note: You can also add the `@bodyParam` annotations to a `\Illuminate\Foundation\Http\FormRequest` subclass:
-
-```php
-/**
- * @bodyParam title string required The title of the post.
- * @bodyParam body string required The title of the post.
- * @bodyParam type string The type of post to create. Defaults to 'textophonious'.
- * @bodyParam author_id int the ID of the author
- * @bodyParam thumbnail image This is required if the post type is 'imagelicious'.
- */
-class MyRequest extends \Illuminate\Foundation\Http\FormRequest
-{
-
-}
-
-public function createPost(MyRequest $request)
-{
-    // ...
-}
-```
-
-### Indicating auth status
-You can use the `@authenticated` annotation on a method to indicate if the endpoint is authenticated. A "Requires authentication" badge will be added to that route in the generated documentation.
-
-### Providing an example response
-You can provide an example response for a route. This will be displayed in the examples section. There are several ways of doing this.
-
-#### @response
-You can provide an example response for a route by using the `@response` annotation with valid JSON:
-
-```php
-/**
- * @response {
- *  "id": 4,
- *  "name": "Jessica Jones",
- *  "roles": ["admin"]
- * }
- */
-public function show($id)
-{
-    return User::find($id);
-}
-```
-
-Moreover, you can define multiple `@response` tags as well as the HTTP status code related to a particular response (if no status code set, `200` will be returned):
-```php
-/**
- * @response {
- *  "id": 4,
- *  "name": "Jessica Jones",
- *  "roles": ["admin"]
- * }
- * @response 404 {
- *  "message": "No query results for model [\App\User]"
- * }
- */
-public function show($id)
-{
-    return User::findOrFail($id);
-}
-```
-
-#### @transformer, @transformerCollection, and @transformerModel
-You can define the transformer that is used for the result of the route using the `@transformer` tag (or `@transformerCollection` if the route returns a list). The package will attempt to generate an instance of the model to be transformed using the following steps, stopping at the first successful one:
-
-1. Check if there is a `@transformerModel` tag to define the model being transformed. If there is none, use the class of the first parameter to the transformer's `transform()` method.
-2. Get an instance of the model from the Eloquent model factory
-2. If the parameter is an Eloquent model, load the first from the database.
-3. Create an instance using `new`.
-
-Finally, it will pass in the model to the transformer and display the result of that as the example response.
-
-For example:
-
-```php
-/**
- * @transformercollection \App\Transformers\UserTransformer
- * @transformerModel \App\User
- */
-public function listUsers()
-{
-    //...
-}
-
-/**
- * @transformer \App\Transformers\UserTransformer
- */
-public function showUser(User $user)
-{
-    //...
-}
-
-/**
- * @transformer \App\Transformers\UserTransformer
- * @transformerModel \App\User
- */
-public function showUser(int $id)
-{
-    // ...
-}
-```
-For the first route above, this package will generate a set of two users then pass it through the transformer. For the last two, it will generate a single user and then pass it through the transformer.
-
-> Note: for transformer support, you need to install the league/fractal package
-
-```bash
-composer require league/fractal
-```
-
-#### @responseFile
-
-For large response bodies, you may want to use a dump of an actual response. You can put this response in a file (as a JSON string) within your Laravel storage directory and link to it. For instance, we can put this response in a file named `users.get.json` in `storage/responses`:
-
-```
-{"id":5,"name":"Jessica Jones","gender":"female"}
-```
-
-Then in your controller, link to it by:
-
-```php
-/**
- * @responseFile responses/users.get.json
- */
-public function getUser(int $id)
-{
-  // ...
-}
-```
-The package will parse this response and display in the examples for this route.
-
-Similarly to `@response` tag, you can provide multiple `@responseFile` tags along with the HTTP status code of the response:
-```php
-/**
- * @responseFile responses/users.get.json
- * @responseFile 404 responses/model.not.found.json
- */
-public function getUser(int $id)
-{
-  // ...
-}
+$app->register(\Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class);
 ```
 
-#### Generating responses automatically
-If you don't specify an example response using any of the above means, this package will attempt to get a sample response by making a request to the route (a "response call"). A few things to note about response calls:
-- They are done within a database transaction and changes are rolled back afterwards.
-- The configuration for response calls is located in the `config/apidoc.php`. They are configured within the `['apply']['response_calls']` section for each route group, allowing you to apply different settings for different sets of routes.
-- By default, response calls are only made for GET routes, but you can configure this. Set the `methods` key to an array of methods or '*' to mean all methods. Leave it as an empty array to turn off response calls for that route group.
-- Parameters in URLs (example: `/users/{user}`, `/orders/{id?}`) will be replaced with '1' by default. You can configure this, however. Put the parameter names (including curly braces and question marks) as the keys and their replacements as the values in the `bindings` key.
-- You can set Laravel config variables (this is useful so you can prevent external services like notifications from being triggered). By default the `app.env` is set to 'documentation'. You can add more variables in the `config` key.
-- By default, the package will generate dummy values for your documented body and query parameters and send in the request. (If you specified example values using `@bodyParam` or `@queryParam`, those will be used instead.) You can configure what headers and additional query and parameters should be sent when making the request (the `headers`, `query`, and `body` keys respectively).
-
-
-### Postman collections
-
-The generator automatically creates a Postman collection file, which you can import to use within your [Postman app](https://www.getpostman.com/apps) for even simpler API testing and usage.
-
-If you don't want to create a Postman collection, set the `postman` config option to false.
-
-The default base URL added to the Postman collection will be that found in your Laravel `config/app.php` file. This will likely be `http://localhost`. If you wish to change this setting you can directly update the url or link this config value to your environment file to make it more flexible (as shown below):
+- Copy the config file from `vendor/mpociot/laravel-apidoc-generator/config/apidoc.php` to your project as `config/apidoc.php`. Then add to your `bootstrap/app.php`:
 
 ```php
-'url' => env('APP_URL', 'http://yourappdefault.app'),
-```
-
-If you are referring to the environment setting as shown above, then you should ensure that you have updated your `.env` file to set the APP_URL value as appropriate. Otherwise the default value (`http://yourappdefault.app`) will be used in your Postman collection. Example environment value:
-
-```
-APP_URL=http://yourapp.app
-```
-
-## Modifying the generated documentation
-
-If you want to modify the content of your generated documentation, go ahead and edit the generated `index.md` file.
-The default location of this file is: `public/docs/source/index.md`.
- 
-After editing the markdown file, use the `apidoc:rebuild` command to rebuild your documentation as a static HTML file.
-
-```sh
-$ php artisan apidoc:rebuild
+$app->configure('apidoc');
 ```
 
-As an optional parameter, you can use `--location` to tell the update command where your documentation can be found.
-
-If you wish to regenerate your documentation, you can run the `generate` command, you can use the `force` option to force the re-generation of existing/modified API routes.
-
-## Automatically add markdown to the beginning or end of the documentation
- If you wish to automatically add the same content to the docs every time you generate, you can add a `prepend.md` and/or `append.md` file to the source folder, and they will be included above and below the generated documentation.
- 
- **File locations:**
-- `public/docs/source/prepend.md` - Will be added after the front matter and info text
-- `public/docs/source/append.md` - Will be added at the end of the document.
-
-## Further modification
 
-This package uses [Documentarian](https://github.com/mpociot/documentarian) to generate the API documentation. If you want to modify the CSS files of your documentation, or simply want to learn more about what is possible, take a look at the [Documentarian guide](http://marcelpociot.de/documentarian/installation).
+## Documentation
+Check out the documentation at [ReadTheDocs](http://laravel-apidoc-generator.readthedocs.io).
 
 ### License
 

TODO.md

@@ -1,4 +1,7 @@
 - Add tests for bindings and bindings prefixes
-- Add tests for config overrdes
+- Add tests for config overrides
 - Add tests for faker seed
-- Add tests on output
+- Add tests on output (deterministic)
+- Remove ungrouped_name for default_group
+- Bring `bindings` outside of `response_calls`
+- Should `routes.*.apply.response_calls.headers` be replaced by `routes.*.apply.headers`?

config/apidoc.php

@@ -116,10 +116,15 @@ return [
                     /*
                      * For URLs which have parameters (/users/{user}, /orders/{id?}),
                      * specify what values the parameters should be replaced with.
-                     * Note that you must specify the full parameter, including curly brackets and question marks if any.
+                     * Note that you must specify the full parameter,
+                     * including curly brackets and question marks if any.
+                     *
+                     * You may also specify the preceding path, to allow for variations,
+                     * for instance 'users/{id}' => 1 and 'apps/{id}' => 'htTviP'.
+                     * However, there must only be one parameter per path.
                      */
                     'bindings' => [
-                        // '{user}' => 1
+                        // '{user}' => 1,
                     ],
 
                     /*

docs/config.md

@@ -1,89 +1,214 @@
 # Configuration
 
-Before you can generate your documentation, you'll need to configure a few things in your `config/apidoc.php`.
+Before you can generate your documentation, you'll need to configure a few things in your `config/apidoc.php`. If you aren't sure what an option does, it's best to leave it set to the default. If you don't have this config file, see the [installation instructions](index.md#installation).
 
-- `output`
-This is the file path where the generated documentation will be written to. Default: **public/docs**
+## `output`
+This is the file path where the generated documentation will be written to. Note that the documentation is generated as static HTML and CSS assets, so the route is accessed directly, and not via the Laravel routing mechanism. This path should be relative to the root of your application. Default: **public/docs**
 
-- `postman`
+## `router`
+The router to use when processing your routes (can be Laravel or Dingo. Defaults to **Laravel**)
+
+## `postman`
 This package can automatically generate a Postman collection for your routes, along with the documentation. This section is where you can configure (or disable) that.
 
-- `router`
-The router to use when processing the route (can be Laravel or Dingo. Defaults to **Laravel**)
+### `enabled`
+Whether or not to generate a Postman API collection. Default: **true**
+
+### `name`
+The name for the exported Postman collection. If you leave this as null, this package will default to `config('app.name')." API"`.
+
+### `description`
+The description for the generated Postman collection.
+
+## `logo`
+You can specify a custom logo to be used on the generated documentation. Set the `logo` option to an absolute path pointing to your logo file. For example:
+```
+'logo' => resource_path('views') . '/api/logo.png'
+```
+
+If you want to use this, please note that the image size must be 230 x 52.
+
+## `default_group`
+When [documenting your api](documenting.md), you use `@group` annotations to group API endpoints. Endpoints which do not have a ggroup annotation will be grouped under the `default_group`. Defaults to **"general"**.
+
+##  `faker_seed`
+When generating example requests, this package uses fzanninoto/faker to generate random values. If you would like the package to generate the same example values for parameters on each run, set this to any number (eg. 1234). (Note: alternatively, you can set example values for parameters when [documenting them.](documenting.md#specifying-request-parameters))
+       
+## `fractal`
+This section only applies if you're using [Transformers]() for your API, and documenting responses with `@transformer` and `@transformerCollection`. Here, you configure how responses are transformed.
+
+> Note: using transformers requires league/fractal package. Run `composer require league/fractal to install
+
+### serializer
+If you are using a custom serializer with league/fractal,  you can specify it here. league/fractal comes with the following serializers:
+- \League\Fractal\Serializer\ArraySerializer::class
+- \League\Fractal\Serializer\DataArraySerializer::class
+- \League\Fractal\Serializer\JsonApiSerializer::class
 
-- `logo`
-You can specify your custom logo to be used on the generated documentation. Set the `logo` option to an absolute path pointing to your logo file.
+Leave this as null to use no serializer or return a simple JSON.
 
-- `routes`
-This is where you specify what rules documentation should be generated for. You specify routes to be parsed by defining conditions that the routes should meet and rules that should be applied when generating documentation. These conditions and rules are specified in groups, allowing you to apply different rules to different routes.
+## `routes`
+The `routes` section is an array of items, describing what routes in your application that should have documentation generated for them. Each item in the array contains rules about what routes belong in that group, and what rules to apply to them. This allows you to apply different settings to different routes.
 
-For instance, suppose your configuration looks like this:
+> Note: This package does not work with Closure-based routes. If you want your route to be captured by this package, you need a controller.
+
+Each item in the `routes` array (a route group) has keys which are explained below. We'll use this sample route definition for a Laravel app to demonstarte them:
 
 ```php
+<?php
+
+Route::group(['domain' => 'api.acme.co'], function () {
+  Route::get('/apps', 'AppController@listApps')
+    ->name('apps.list');
+  Route::get('/apps/{id}', 'AppController@getApp')
+    ->name('apps.get');
+  Route::post('/apps', 'AppController@createApp')
+    ->name('apps.create');
+  Route::get('/users', 'UserController@listUsers')
+    ->name('users.list');
+  Route::get('/users/{id}', 'UserController@getUser')
+    ->name('users.get');
+});
+
+Route::group(['domain' => 'public-api.acme.co'], function () {
+  Route::get('/stats', 'PublicController@getStats')
+    ->name('public.stats');
+});
+
+Route::group(['domain' => 'status.acme.co'], function () {
+  Route::get('/status', 'PublicController@getStatus')
+    ->name('status');
+});
+```
+
+### `match`
+In this section, you define the rules that will be used to determine what routes in your application fall into this group. There are three kinds of rules defined here (keys in the `match` array):
+
+#### `domains`
+This key takes an array of domain names as its value. Only routes which are defined on the domains specified here will be matched as part of this group. For instance, in our sample routes above, we may wish to apply different settings to documentation based on the domains. For instance, the routes on the `api.acme.co` domain need authentication, while those on the other domains do not. We can searate them into two groups like this:
+
+```php
+<?php
 return [
-     //...,
+  //...,
   
-     'routes' => [
-          [
-              'match' => [
-                  'domains' => ['*'],
-                  'prefixes' => ['api/*', 'v2-api/*'],
-                  'versions' => ['v1'],
-              ],
-              'include' => ['users.index', 'healthcheck*'],
-              'exclude' => ['users.create', 'admin.*'],
-              'apply' => [
-                  'headers' => [
-                      'Authorization' => 'Bearer: {token}',
-                  ],
-              ],
-          ],
+  'routes' => [
+    [
+      'match' => [
+        'domains' => ['api.acme.co'],
+        'prefixes' => ['*'],
+      ],
+      'apply' => [
+        'headers' => [ 'Authorization' => 'Bearer {your-token}']
+      ]
+    ],
+    [
+      'match' => [
+        'domains' => ['public-api.acme.co', 'status.acme.co'],
+        'prefixes' => ['*'],
+      ],
+    ],
+  ],
 ];
 ```
+The first group will match all routes on the 'api.acme.co' domain, and add a header 'Authorization: Bearer {your-token}' to the examples in the generated documentation. The second group will pick up the other routes. The Authorization header will not be added for those ones.
 
-This means documentation will be generated for routes in all domains ('&ast;' is a wildcard meaning 'any character') which match any of the patterns 'api/&ast;' or 'v2-api/&ast;', excluding the 'users.create' route and any routes whose names begin with `admin.`, and including the 'users.index' route and any routes whose names begin with `healthcheck.`. (The `versions` key is ignored unless you are using Dingo router).
-Also, in the generated documentation, these routes will have the header 'Authorization: Bearer: {token}' added to the example requests.
+You can use the `*` wildcard to match all domains (or as a placeholder in a pattern).
 
-You can also separate routes into groups to apply different rules to them:
+#### `prefixes`
+The prefixes key is similar to the `domains` key, but is based on URL path prefixes (ie. what the part starts with, after the domain name). You could use prefixes to rewrite our example configuration above in a different way:
 
 ```php
 <?php
 return [
-     //...,
+  //...,
   
-     'routes' => [
-          [
-              'match' => [
-                  'domains' => ['v1.*'],
-                  'prefixes' => ['*'],
-              ],
-              'include' => [],
-              'exclude' => [],
-              'apply' => [
-                  'headers' => [
-                      'Token' => '{token}',
-                      'Version' => 'v1',
-                  ],
-              ],
-          ],
-          [
-              'match' => [
-                  'domains' => ['v2.*'],
-                  'prefixes' => ['*'],
-              ],
-              'include' => [],
-              'exclude' => [],
-              'apply' => [
-                  'headers' => [
-                      'Authorization' => 'Bearer: {token}',
-                      'Api-Version' => 'v2',
-                  ],
-              ],
-          ],
+  'routes' => [
+    [
+      'match' => [
+         'domains' => ['*'],
+         'prefixes' => ['users/*', 'apps/*'],
+       ],
+       'apply' => [
+         'headers' => [ 'Authorization' => 'Bearer {your-token}']
+       ]
+    ],
+    [
+      'match' => [
+         'domains' => ['*'],
+         'prefixes' => ['stats/*', 'status/*'],
+      ],
+    ],
+  ],
 ];
 ```
 
-With the configuration above, routes on the `v1.*` domain will have the `Token` and `Version` headers applied, while routes on the `v2.*` domain will have the `Authorization` and `Api-Version` headers applied.
+This would achieve the same as the first configuration. As with domains, the `*` character is a wildcard. This means you can set up a ingle group to match all your routes by using `'domains' => ['*'], 'prefixes' => ['*']`. (This is set by default.)
+
+> The `domains` and `prefixes` keys are both required for all route groups.
+
+#### `versions`
+> This section only applies if you're using Dingo Router
+
+When using Dingo's Router, all routes must be specified inside versions. This means that you must specify the versions to be matched along with the domains and prefixes when describing a route group. Note that wildcards in `versions` are not supported; you must list out all your versions explicitly. Example:
+
+ ```php
+<?php
+return [
+  //...,
+  
+  'routes' => [
+    [
+      'match' => [
+        'domains' => ['*'],
+        'prefixes' => ['*'],
+        'versions' => ['v1', 'beta'], // only if you're using Dingo router
+      ],
+    ],
+  ],
+];
+```
+
+### `include` and `exclude`
+The `include` key holds an array of route names which should be included in this group, *even if they do not match the rules in the `match` section*.
+The `exclude` key holds an array of route names which should be excluded from this group, *even if they match the rules in the `match` section*.
+
+> Remember that these two keys work with route *names*, not paths.
+
+Using our above sample routes, asuming you wanted to place the `users.list` route in the second group (no Authorization header), here's how you could do it:
+
+```php
+<?php
+return [
+  //...,
+  
+  'routes' => [
+    [
+      'match' => [
+        'domains' => ['api.acme.co'],
+        'prefixes' => ['*'],
+      ],
+      'exclude' => ['users.list'],
+      'apply' => [
+        'headers' => [ 'Authorization' => 'Bearer {your-token}']
+      ]
+    ],
+    [
+      'match' => [
+        'domains' => ['public-api.acme.co', 'status.acme.co'],
+        'prefixes' => ['*'],
+      ],
+      'include' => ['users.list'],
+    ],
+  ],
+];
+```
+
+### `apply`
+After defining the routes in `match` (and `include` or `exclude`), `apply` is where you specify the settings to be applied to those routes when generating documentation. There are a bunch of settings you can tweak here:
+
+#### `headers`
+Like we've demonstrated above, any headers you specify here will be added to the headers shown in the example requests in your documenation. Headers are specified as key => value strings.
 
-> Note: the `include` and `exclude` items are arrays of route names. THe &ast; wildcard is supported.
-> Note: If you're using DIngo router, the `versions` parameter is required in each route group. This parameter does not support wildcards. Each version must be listed explicitly,
+#### `response_calls`
+These are the settings that will be applied when making ["response calls"](documenting.md#generating-responses-automatically). See the linked section for details.

docs/description.md

@@ -0,0 +1,9 @@
+# How This Works
+
+After installing this package and runing the command `php artisan apidoc:generate` in your application, here's what happens:
+
+- The package fetches all your application's routes.
+- It looks through your [configuration file](config.md) to filter the routes to the ones you actually want to document. For each route, it retrieves the settings you want to apply to it, if any.
+- It processes each route. "Process" here involves using a number of strategies to extract the route's information: group, title, description, body parameters, query parameters, and a sample response, if possible.
+- After processing the routes, it generates a markdown file describing the routes from the parsed data and passes them to [Documentarian](https://github.com/mpociot/documentarian), which wraps them in a theme and converts them into HTML and CSS.
+- It generates a Postman API collection for your routes. ([This can be disabled.](config.md#postman))

docs/documenting.md

@@ -1,15 +1,15 @@
 # Documenting Your API
-This package uses these resources to generate the API documentation:
+This package generates documentation from your code using mainly annotations (in doc block comments).
 
 ## Grouping endpoints
+All endpoints are grouped for easy organization. Using `@group` in a controller doc block creates a Group within the API documentation. All routes handled by that controller will be grouped under this group in the table of conetns shown in the sidebar. 
 
-This package uses the HTTP controller doc blocks to create a table of contents and show descriptions for your API methods.
+The short description after the `@group` should be unique to allow anchor tags to navigate to this section. A longer description can be included below. Custom formatting and `<aside>` tags are also supported. (see the [Documentarian docs](http://marcelpociot.de/documentarian/installation/markdown_syntax))
 
-Using `@group` in a controller doc block creates a Group within the API documentation. All routes handled by that controller will be grouped under this group in the sidebar. The short description after the `@group` should be unique to allow anchor tags to navigate to this section. A longer description can be included below. Custom formatting and `<aside>` tags are also supported. (see the [Documentarian docs](http://marcelpociot.de/documentarian/installation/markdown_syntax))
+ > Note: using `@group` is optional. Ungrouped routes will be placed in a default group.
 
- > Note: using `@group` is optional. Ungrouped routes will be placed in a "general" group.
+Above each route in the controller, you should have a doc block. This should include a unique short description as the first entry. An optional second entry can be added with further information. Both descriptions will appear in the API documentation in a different format as shown below.
 
-Above each method within the controller you wish to include in your API documentation you should have a doc block. This should include a unique short description as the first entry. An optional second entry can be added with further information. Both descriptions will appear in the API documentation in a different format as shown below.
 You can also specify an `@group` on a single method to override the group defined at the controller level.
 
 ```php
@@ -48,11 +48,11 @@ class UserController extends Controller
 ![Doc block result](http://headsquaredsoftware.co.uk/images/api_generator_docblock.png)
 
 ## Specifying request parameters
-
 To specify a list of valid parameters your API route accepts, use the `@bodyParam` and `@queryParam` annotations.
 - The `@bodyParam` annotation takes the name of the parameter, its type, 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 `@queryParam` annotation takes the name of the parameter, an optional "required" label, and then its description,
 
+Examples:
 
 ```php
 /**
@@ -97,14 +97,15 @@ Note: a random value will be used as the value of each parameter in the example
      */
 ```
 
-Note: You can also add the `@bodyParam` annotations to a `\Illuminate\Foundation\Http\FormRequest` subclass:
+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
 
 ```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 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
+ * @bodyParam author_id int the ID of the author. Example: 2
  * @bodyParam thumbnail image This is required if the post type is 'imagelicious'.
  */
 class MyRequest extends \Illuminate\Foundation\Http\FormRequest
@@ -112,13 +113,14 @@ class MyRequest extends \Illuminate\Foundation\Http\FormRequest
 
 }
 
+// in your controller...
 public function createPost(MyRequest $request)
 {
     // ...
 }
 ```
 
-### Indicating auth status
+### Indicating authentication status
 You can use the `@authenticated` annotation on a method to indicate if the endpoint is authenticated. A "Requires authentication" badge will be added to that route in the generated documentation.
 
 ### Providing an example response
@@ -141,7 +143,7 @@ public function show($id)
 }
 ```
 
-Moreover, you can define multiple `@response` tags as well as the HTTP status code related to a particular response (if no status code set, `200` will be returned):
+Moreover, you can define multiple `@response` tags as well as the HTTP status code related to a particular response (if no status code set, `200` will be assumed):
 ```php
 /**
  * @response {
@@ -241,9 +243,15 @@ public function getUser(int $id)
 
 ### Generating responses automatically
 If you don't specify an example response using any of the above means, this package will attempt to get a sample response by making a request to the route (a "response call"). A few things to note about response calls:
-- They are done within a database transaction and changes are rolled back afterwards.
-- The configuration for response calls is located in the `config/apidoc.php`. They are configured within the `['apply']['response_calls']` section for each route group, allowing you to apply different settings for different sets of routes.
+
+- Response calls are done within a database transaction and changes are rolled back afterwards.
+
+- The configuration for response calls is located in the `config/apidoc.php`. They are configured within the `apply.response_calls` section for each route group, allowing you to apply different settings for different sets of routes.
+
 - By default, response calls are only made for GET routes, but you can configure this. Set the `methods` key to an array of methods or '*' to mean all methods. Leave it as an empty array to turn off response calls for that route group.
-- Parameters in URLs (example: `/users/{user}`, `/orders/{id?}`) will be replaced with '1' by default. You can configure this, however. Put the parameter names (including curly braces and question marks) as the keys and their replacements as the values in the `bindings` key.
-- You can set Laravel config variables (this is useful so you can prevent external services like notifications from being triggered). By default the `app.env` is set to 'documentation'. You can add more variables in the `config` key.
+
+- Parameters in URLs (example: `/users/{user}`, `/orders/{id?}`) will be replaced with '1' by default. You can configure this, however. Put the parameter names (including curly braces and question marks) as the keys and their replacements as the values in the `bindings` key. You may also specify the preceding path, to allow for variations; for instance, you can set `['users/{id}' => 1, 'apps/{id}' => 'htTviP']`. However, there must only be one parameter per path (ie `users/{name}/{id}` is invalid).
+
+- You can set Laravel config variables. This is useful so you can prevent external services like notifications from being triggered. By default the `app.env` is set to 'documentation'. You can add more variables in the `config` key.
+
 - By default, the package will generate dummy values for your documented body and query parameters and send in the request. (If you specified example values using `@bodyParam` or `@queryParam`, those will be used instead.) You can configure what headers and additional query and parameters should be sent when making the request (the `headers`, `query`, and `body` keys respectively).

docs/generating-documentation.md

@@ -8,3 +8,34 @@ php artisan apidoc:generate
 ```
 
 It will generate documentation using your specified configuration. The documentation will be generated as static HTML and CSS assets within the specified output folder.
+
+## Regenerating
+When you make changes to your routes, you can safely regenerate your documentation by running the `generate` command. This will rewrite the documentation for only the routes you have changed. You can use the `force` option to force the regeneration of existing/unmodified API routes.
+
+## Postman collections
+
+The generator automatically creates a Postman collection file, which you can import to use within your [Postman app](https://www.getpostman.com/apps) for even simpler API testing and usage.
+
+If you don't want to create a Postman collection, set the `postman.enabled` config option to false.
+
+The base URL added to the Postman collection will be the value of the `url` key in your Laravel `config/app.php` file. 
+
+## Manually modifying the content of the generated documentation
+If you want to modify the content of your generated documentation without changing the routes, go ahead and edit the generated `index.md` file.
+
+This file is located in the `source` folder of  your `output` directory (see [configuration](config.md#output)), so by default, this is `public/docs/source/index.md`.
+ 
+After editing the markdown file, you can use the `apidoc:rebuild` command to rebuild your documentation into HTML.
+
+```sh
+php artisan apidoc:rebuild
+```
+
+## Automatically add markdown to the beginning or end of the documentation
+ If you wish to automatically add the same content to the docs every time you generate (for instance, an introduction, a disclaimer or an authenticatino guide), you can add a `prepend.md` and/or `append.md` file to the `source` folder in the `output` directory, and they will be added to the generated documentation. 
+ 
+ The contents of `prepend.md` will be added after the front matter and info text, while the contents of `append.md` will be added at the end of the document.
+
+## Further modification
+
+This package uses [Documentarian](https://github.com/mpociot/documentarian) to generate the API documentation. If you want to modify the CSS files of your documentation, or simply want to learn more about what is possible, take a look at the [Documentarian guide](http://marcelpociot.de/documentarian/installation).

docs/index.md

@@ -5,6 +5,7 @@ Automatically generate your API documentation from your existing Laravel/Lumen/[
 `php artisan apidoc:generate`
 
 ## Contents
+* [How This Works](description.md)
 * [Configuration](config.md)
 * [Generating Documentation](generating-documentation.md)
 * [Documenting Your API](documenting.md)