Updated README, added update documentation command

README.md

@@ -1,5 +1,7 @@
 ## Laravel API Documentation Generator
 
+Automatically generate your API documentation from your existing Laravel routes.
+
 `php artisan api:gen --routePrefix=settings/api/*`
 
 ![image](http://img.shields.io/packagist/v/mpociot/laravel-apidoc-generator.svg?style=flat)
@@ -9,12 +11,12 @@
 [![Build Status](https://travis-ci.org/mpociot/laravel-apidoc-generator.svg?branch=master)](https://travis-ci.org/mpociot/laravel-apidoc-generator)
 
 
-### Install
+## Installation
 
 Require this package with composer using the following command:
 
 ```bash
-composer require mpociot/laravel-apidoc-generator
+$ composer require mpociot/laravel-apidoc-generator
 ```
 Go to your `config/app.php` and add the service provider:
 
@@ -22,17 +24,87 @@ Go to your `config/app.php` and add the service provider:
 Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class
 ```
 
-### Usage
+## Usage
+
+To generate your API documentation, use the `api:generate` artisan command.
+
+```bash
+$ php artisan api:generate --routePrefix=api/v1/*
+```
+
+This command will scan your applications routes for the URIs matching `api/v1/*` and will parse these controller methods and form requests.
+
+### Available command options:
+
+Option | Description
+--------- | ------- | ------- | ------- | -----------
+`output` | The output path used for the generated documentation. Default: `public/docs`
+`routePrefix` | The route prefix to use for generation - `*` can be used as a wildcard
+`routes ` | The route names to use for generation - Required if no routePrefix is provided
+`actAsUserId ` | The user ID to use for authenticated API response calls
+
+### How does it work?
+
+This package uses these resources to generated the API documentation:
+
+#### Controller doc block
+
+This package uses the HTTP controller doc blocks to create a table of contents and show descriptions for your API methods.
+
+```php
+/**
+ * This is the short description
+ *
+ * This can be an optional longer description of your API call, used within the documentation.
+ *
+ */
+ public function foo()
+```
+
+#### Form request validation rules
 
+To display a list of valid parameters, your API methods accepts, this package uses Laravels [Form Requests Validation](https://laravel.com/docs/5.2/validation#form-request-validation).
 
+
+```php
+public function rules()
+{
+    return [
+        'title' => 'required|max:255',
+        'body' => 'required',
+    ];
+}
+```
+
+#### API responses
+
+If your API route accepts a `GET` method, this package tries to call the API route with all middleware disabled to fetch an example API response. 
+
+If your API needs an authenticated user, you can use the `actAsUserId` option to specify a user ID that will be used for making these API calls:
+
+```bash
+$ php artisan api:generate --routePrefix=api/* --actAsUserId=1
 ```
-php artisan api:generate 
-    {--output=public/docs : The output path for the generated documentation}
-    {--routePrefix= : The route prefix to use for generation - * can be used as a wildcard}
-    {--routes=* : The route names to use for generation - if no routePrefix is provided}
-    {--actAsUserId= : The user ID to use for API response calls}
+
+> Note: The example API responses work best with seeded data.
+
+
+## Modify 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 `api:update` command to rebuild your documentation as a static HTML file.
+
+```bash
+$ php artisan api:update
 ```
 
+As an optional parameter, you can use `--location` to tell the update command where your documentation can be found.
+
+## 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 [Documentarion guide](http://marcelpociot.com/documentarian/installation).
 
 ### License
 

src/Mpociot/ApiDoc/ApiDocGeneratorServiceProvider.php

@@ -4,6 +4,7 @@ namespace Mpociot\ApiDoc;
 
 use Illuminate\Support\ServiceProvider;
 use Mpociot\ApiDoc\Commands\GenerateDocumentation;
+use Mpociot\ApiDoc\Commands\UpdateDocumentation;
 
 class ApiDocGeneratorServiceProvider extends ServiceProvider
 {
@@ -26,9 +27,13 @@ class ApiDocGeneratorServiceProvider extends ServiceProvider
         $this->app['apidoc.generate'] = $this->app->share(function () {
             return new GenerateDocumentation();
         });
+        $this->app['apidoc.update'] = $this->app->share(function () {
+            return new UpdateDocumentation();
+        });
 
         $this->commands(
-            'apidoc.generate'
+            'apidoc.generate',
+            'apidoc.update',
         );
     }
 

src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php

@@ -11,10 +11,6 @@ use Symfony\Component\Process\Process;
 
 class GenerateDocumentation extends Command
 {
-    /**
-     * The Whiteboard repository URL
-     */
-    const WHITEBOARD_REPOSITORY = 'https://github.com/mpociot/whiteboard.git';
 
     /**
      * The name and signature of the console command.
@@ -33,7 +29,7 @@ class GenerateDocumentation extends Command
      *
      * @var string
      */
-    protected $description = 'Command description';
+    protected $description = 'Generate your API documentation from existing Laravel routes.';
 
     /**
      * Create a new command instance.

src/Mpociot/ApiDoc/Commands/UpdateDocumentation.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Mpociot\ApiDoc\Commands;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Route;
+use Mpociot\ApiDoc\ApiDocGenerator;
+use Mpociot\Documentarian\Documentarian;
+use phpDocumentor\Reflection\DocBlock;
+use Symfony\Component\Process\Process;
+
+class UpdateDocumentation extends Command
+{
+
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'api:update 
+                            {--location=public/docs : The documentation location}
+    ';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Update and rebuild your API documentation from your markdown file.';
+
+    /**
+     * Create a new command instance.
+     *
+     * @return void
+     */
+    public function __construct()
+    {
+        parent::__construct();
+    }
+
+    /**
+     * Execute the console command.
+     *
+     * @return mixed
+     */
+    public function handle()
+    {
+        $outputPath = $this->option('location');
+
+        $documentarian = new Documentarian();
+
+        if (!is_dir($outputPath)) {
+            $this->error('There is no generated documentation available at '.$outputPath.'.');
+            return false;
+        }
+        $this->info('Updating API HTML code');
+
+        $documentarian->generate($outputPath);
+
+        $this->info('Wrote HTML documentation to: ' . $outputPath . '/public/index.html');
+    }
+
+}