mpociot / laravel-apidoc-generator

Laravel API Documentation Generator

Laravel API Documentation Generator

Automatically generate your API documentation from your existing Laravel/Lumen/Dingo routes.

php artisan apidoc:generate

Installation

PHP 7.2 and Laravel/Lumen 5.7 or higher are required.

If your application does not meet these requirements, you can check out the 3.x branch for older releases.

composer require --dev mpociot/laravel-apidoc-generator

Laravel

Publish the config file by running:

php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config

This will create an apidoc.php file in your config folder.

Lumen

• When using Lumen, you will need to run composer require mpociot/laravel-apidoc-generator instead.
• Register the service provider in your bootstrap/app.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:

$app->configure('apidoc');

Documentation

Check out the documentation at the Beyond Code homepage.

License

The Laravel API Documentation Generator is free software licensed under the MIT license.

laravel-apidoc-generator's Issues

Customization

Dear @mpociot ,
I really like this plugin from what I've seen so far. It is awesome 👍

However, when looking at your demo documentation, I have a few questions:

• How can I write a custom Info text?
• In my generated api-doc I have a Available Routes section - which is empty?!
• How can I add additional programming languages, like PHP or Ruby
• How can I add success, warning or error tags to endpoints (e.g., like the Remember — a happy kitten is an authenticated kitten! shown in your demo documentation?
• How can I auto-generate Errors from my API?
• At the moment, the api-docs outputs all entries (e.g., all FAQs which are stored in the database). Can I limit this down to X entries? Or even fake entries?
• Transformers used to transform the output are ignored (at least for me). How do I output my data like when using postman?
• How to sum up endpoints to groups (--> Solution already found in #36 )

Is it possible to address these issues all within the API (code) itself or use respective commands? I would not like to manually edit respective *.md or *.html files, as I would like to continuously auto-generate my api-docs.

Sorry for the long list of questions ;)

Greetings from Germany

explode() expects parameter 2 to be string, object given

Hi, I keep getting the following error message: explode() expects parameter 2 to be string, object given

I tried the following:

php artisan api:gen --routePrefix="api/v1/"
php artisan api:generate --routePrefix="api/v1/"
php artisan api:generate --routePrefix="api/v1/*" --actAsUserId=1

routes.php

if (config('system.enable_api') === true)
{
    Route::group(['middleware' => 'api', 'prefix' => 'api/v1'], function ()
    {
        Route::get('test', function ()
        {
            return 'API Enabled';
        });

        Route::post('authenticate', 'TokenController@authenticate');
        Route::get('authenticate/refresh', 'TokenController@refreshToken');

        // http://<site>/public/api/v1/admin/users/update
        Route::group(['middleware' => 'jwt.auth','prefix' => 'admin/users'], function ()
        {
            Route::get('authenticate/user', 'TokenController@getAuthenticatedUser');
            Route::get('list', 'Admin\UserController@getList');
            Route::get('get/{id?}', 'Admin\UserController@get');
            Route::post('store', 'Admin\UserController@postStore');
            Route::post('update', 'Admin\UserController@postUpdate');
        });

    });
}

Encoding problem

"first_name": "\u0410\u043b\u0435\u043a\u0441\u0430\u043d\u0434\u044a\u0440",

this example with cyrillic text in "Example response"

Multi language

Thank for this great tool!
Excuse me for bad english!
I want to translate Description AbstractGenetator.php into Chinese.

It is not good to change directly on the basis of the original text. Can be changed into the form of a configuration file

Issue with these routes

Hey,

I have a issue with these routes. Am I doing something wrong?

Route::group([
    'namespace'  => 'Api',
    'middleware' => 'api',
], function () {
    Route::group([
        'namespace' => 'v1',
        'prefix'    => 'v1'
    ], function () {

        Route::post('authenticate', ['as' => 'authenticate', 'uses' => 'AuthenticationController@authenticate']);
        Route::get('me', 'AuthenticationController@me');
    });
});

Doing php artisan route:list I get:

Method	URI	Action
POST	v1/authenticate	App\Http\Controllers\Api\v1\AuthenticationController@authenticate
GET	v1/me	App\Http\Controllers\Api\v1\AuthenticationController@me

When I run php artisan api:generate --routePrefix=v1/* I get no matches found: --routePrefix=v1/*

When I run php artisan api:generate --routePrefix=v1 it finds the routes but the output is blank.

Not for Lumen?

in my lumen project, I run the installation with composer, and I got errors.

Call to undefined function Mpociot\ApiDoc\resource_path()

I'm running

Laravel Framework version 5.1.19 (LTS)

on

PHP 5.6.19 (cli) (built: Mar 4 2016 23:38:37)
Copyright (c) 1997-2016 The PHP Group
Zend Engine v2.6.0, Copyright (c) 1998-2016 Zend Technologies
with Zend OPcache v7.0.6-dev, Copyright (c) 1999-2016, by Zend Technologies
with Xdebug v2.4.0, Copyright (c) 2002-2016, by Derick Rethans

After installing with the following actions

composer update

composer require mpociot/laravel-apidoc-generator

 # adding this to config/app.php::'providers'
/*
 * ApiDoc Generator
 */
Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class,

I ran

php artisan vendor:publish

And got

php artisan vendor:publish
PHP Fatal error:  Call to undefined function Mpociot\ApiDoc\resource_path() in [redacted]/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/ApiDocGeneratorServiceProvider.php on line 22
PHP Stack trace:
PHP   1. {main}() [redacted]/artisan:0
PHP   2. Illuminate\Foundation\Console\Kernel->handle() [redacted]/artisan:36
PHP   3. Illuminate\Foundation\Console\Kernel->bootstrap() [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php:98
PHP   4. Illuminate\Foundation\Application->bootstrapWith() [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php:201
PHP   5. Illuminate\Foundation\Bootstrap\BootProviders->bootstrap() [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Application.php:203
PHP   6. Illuminate\Foundation\Application->boot() [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/BootProviders.php:17
PHP   7. array_walk() [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Application.php:718
PHP   8. Illuminate\Foundation\Application->Illuminate\Foundation\{closure}() [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Application.php:718
PHP   9. Illuminate\Foundation\Application->bootProvider() [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Application.php:717
PHP  10. Illuminate\Container\Container->call() [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Application.php:734
PHP  11. call_user_func_array:{/[redacted]/vendor/laravel/framework/src/Illuminate/Container/Container.php:503}() [redacted]/vendor/laravel/framework/src/Illuminate/Container/Container.php:503
PHP  12. Mpociot\ApiDoc\ApiDocGeneratorServiceProvider->boot()[redacted]/vendor/laravel/framework/src/Illuminate/Container/Container.php:503


  [Symfony\Component\Debug\Exception\FatalErrorException]    
  Call to undefined function Mpociot\ApiDoc\resource_path()  

I have tried to following:

php artisan clear-compiled

# verified it was deleted

php artisan optimize

I also deleted my vendor directory and ran composer install

same errors

laravel log:

[2016-06-24 18:52:31] local.ERROR: exception 'Symfony\Component\Debug\Exception\FatalErrorException' with message 'Call to undefined function Mpociot\ApiDoc\resource_path()' in [redacted]/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/ApiDocGeneratorServiceProvider.php:22
Stack trace:
#0 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(133): Symfony\Component\Debug\Exception\FatalErrorException->__construct()
#1 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(118): Illuminate\Foundation\Bootstrap\HandleExceptions->fatalExceptionFromError()
#2 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(0): Illuminate\Foundation\Bootstrap\HandleExceptions->handleShutdown()
#3 [redacted]/vendor/laravel/framework/src/Illuminate/Container/Container.php(503): Mpociot\ApiDoc\ApiDocGeneratorServiceProvider->boot()
#4 [redacted]/vendor/laravel/framework/src/Illuminate/Container/Container.php(503): call_user_func_array:{[redacted]/vendor/laravel/framework/src/Illuminate/Container/Container.php:503}()
#5 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(734): Illuminate\Container\Container->call()
#6 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(717): Illuminate\Foundation\Application->bootProvider()
#7 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(718): Illuminate\Foundation\Application->Illuminate\Foundation\{closure}()
#8 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(718): array_walk()
#9 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/BootProviders.php(17): Illuminate\Foundation\Application->boot()
#10 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(203): Illuminate\Foundation\Bootstrap\BootProviders->bootstrap()
#11 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php(201): Illuminate\Foundation\Application->bootstrapWith()
#12 [redacted]/vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php(98): Illuminate\Foundation\Console\Kernel->bootstrap()
#13 [redacted]/artisan(36): Illuminate\Foundation\Console\Kernel->handle()
#14 [redacted]/artisan(0): {main}()
#15 {main}  

Creating groups in the documentation

http://marcelpociot.com/whiteboard/

Checking the example, there are some groups created (Authentication, Kittens, Errors) and some of them have warnings and special content,

Is it possible to generate those groups and warnings by changing the DocBlock, or should I edit the generated index.md to accomplish this?

Thanks.

is it possible to add custom example response in php block?

as the post api response cannot be automatically generated, is that possible to add custom example response?

thanks!

--noResponseCalls throws ErrorException Trying to get property of non-object

Seems to happen whenever I set the flag --noResponseCallsApi

Example Controller:

class ApiController extends Controller { public function get() { return Response::json(array( 'error' => false, 'urls' => []), 200 ); } }

Example Route:

Route::get('/api/test', 'ApiController@get');

Generated link to Postman collection.json is broken

Hi there,

it seems like there is something wrong with the link to the Postman Collection generated in resources/views/partials/info.blade.php. The $outputPath gets appended to the link here. This basically breaks the link, as for me, the Anchor looks like this:

<a href="public/docs/collection.json">Get Postman Collection</a>

which leads to the user agent trying to fetch /docs/public/docs/collection.json.

In my understanding, setting href="collection.json" should be sufficient, as this file lives in the same directory as index.html does. Or am I missing something here?

Error api:generate Laravel 5.3

Execute commands: php artisan api:generate --routePrefix="api/v1/*"

Routers are located in the file routes/api.php

As a result, it generates a blank document

[Proposal] Route Model Bindings

I am currently working on adding support for Route Model Bindings which at the moment looks like this.

php artisan api:generate --routePrefix=v1 --router=dingo --bindings="company,1|language,1|taxrate,1"

This would get transformed into an array with [company => 1, language => 1, taxrate => 1].

Would this syntax for adding the bindings fine or would another way be preferred?

Unable to translate when language is != 'en'

I started out with this error message:

  [Symfony\Component\Debug\Exception\FatalErrorException]                                                                                                                      
  Method Illuminate\View\View::__toString() must not throw an exception, caught ErrorException: Array to string conversion (View:(…)/vendor/mpociot/larave  
  l-apidoc-generator/src/resources/views/documentarian.blade.php)   

The error occurs when the parameter descriptions on line 84 of the blade view are just empty arrays in multiple dimensions. This is caused by the system being unable to translate the parameters. I thought I had forgotten to publish the lang files, but it turns out I was just using a locale different than 'en'.

So: If the default language of the Laravel install is something other than 'en', then the translation of the rules and parsing of rule descriptions will fail miserably. Perhaps this could be amended somehow? It says in the readme that it will return the descriptions in the main language of the application but it seems it will only return the descriptions in the 'en' language.

php artisan api:generate --routePrefix=api/v1/*

// api
Route::group(['namespace' => 'api','prefix'=>'api/v1'], function()
{
Route::get('index', 'ApiController@index');

// 新增
Route::get('detail', 'ApiController@detail');
});

再次执行 php artisan api:generate --routePrefix=api/v1/* 访问首页并没有新增的 detail 这个，请问什么原因？

Please provide a valid cache path. Laravel 5.3

When i execute

php artisan api:generate --routePrefix="api/v1/users" i got this error:

Processed route: [GET,HEAD] api/v1/users
Processed route: [POST] api/v1/users

[InvalidArgumentException]          
Please provide a valid cache path.    

My route list:

+--------+-----------+---------------------+---------------+-------------------------------------------------------+------------+
| Domain | Method    | URI                 | Name          | Action                                                | Middleware |
+--------+-----------+---------------------+---------------+-------------------------------------------------------+------------+
|        | GET|HEAD  | api/v1/users        | users.index   | \App\Modules\User\Controllers\BasicController@index   | api        |
|        | POST      | api/v1/users        | users.store   | \App\Modules\User\Controllers\BasicController@store   | api        |
|        | GET|HEAD  | api/v1/users/{user} | users.show    | \App\Modules\User\Controllers\BasicController@show    | api        |
|        | PUT|PATCH | api/v1/users/{user} | users.update  | \App\Modules\User\Controllers\BasicController@update  | api        |
|        | DELETE    | api/v1/users/{user} | users.destroy | \App\Modules\User\Controllers\BasicController@destroy | api        |
+--------+-----------+---------------------+---------------+-------------------------------------------------------+------------+

Anyone can help?

Broken type validation 'string' using between

When I setup string with between like this
'name' => ['required', 'string', 'between:3,150'],

I getting wrong type
name numeric required Between: 3 and 150

But when i set min, max it's ok.

Strange error

I have this method

/*
 *  API Login, on success return JWT Auth token
 *
 * @param \Illuminate\Http\Request $request
 *
 * @return \Illuminate\Http\JsonResponse
 */
public function login(Request $request)
{
    // grab credentials from the request
    $credentials = $request->only('email', 'password');
    try {
        // attempt to verify the credentials and create a token for the user
        if (!$token = JWTAuth::attempt($credentials)) {
            return response()->json(['error' => 'invalid_credentials'], 401);
        }
    } catch (JWTException $e) {
        // something went wrong whilst attempting to encode the token
        return response()->json(['error' => 'could_not_create_token'], 500);
    }

    // all good so return the token
    return response()->json(compact('token'));
}

When I run php artisan api:generate --router="dingo" --routePrefix="v1" I get

[2016-06-20 20:33:51] local.INFO: App\Http\Controllers\v1\SessionsController@login  
[2016-06-20 20:33:51] local.ERROR: exception 'InvalidArgumentException' with message 'Expected a string. Got: boolean' in /vagrant/vendor/webmozart/assert/src/Assert.php:133
Stack trace:
#0 /vagrant/vendor/phpdocumentor/reflection-docblock/src/DocBlock.php(60): Webmozart\Assert\Assert::string(false)
#1 /vagrant/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/Generators/AbstractGenerator.php(100): phpDocumentor\Reflection\DocBlock->__construct(false)
#2 /vagrant/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/Generators/DingoGenerator.php(29): Mpociot\ApiDoc\Generators\AbstractGenerator->getRouteDescription('App\\...')
#3 /vagrant/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php(200): Mpociot\ApiDoc\Generators\DingoGenerator->processRoute(Object(Dingo\Api\Routing\Route), Array, true)
#4 /vagrant/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php(74): Mpociot\ApiDoc\Commands\GenerateDocumentation->processDingoRoutes(Object(Mpociot\ApiDoc\Generators\DingoGenerator), Array, 'v1')
#5 [internal function]: Mpociot\ApiDoc\Commands\GenerateDocumentation->handle()
#6 /vagrant/vendor/laravel/framework/src/Illuminate/Container/Container.php(507): call_user_func_array(Array, Array)
#7 /vagrant/vendor/laravel/framework/src/Illuminate/Console/Command.php(169): Illuminate\Container\Container->call(Array)
#8 /vagrant/vendor/symfony/console/Command/Command.php(256): Illuminate\Console\Command->execute(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#9 /vagrant/vendor/laravel/framework/src/Illuminate/Console/Command.php(155): Symfony\Component\Console\Command\Command->run(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#10 /vagrant/vendor/symfony/console/Application.php(791): Illuminate\Console\Command->run(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#11 /vagrant/vendor/symfony/console/Application.php(186): Symfony\Component\Console\Application->doRunCommand(Object(Mpociot\ApiDoc\Commands\GenerateDocumentation), Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#12 /vagrant/vendor/symfony/console/Application.php(117): Symfony\Component\Console\Application->doRun(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#13 /vagrant/vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php(107): Symfony\Component\Console\Application->run(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#14 /vagrant/artisan(36): Illuminate\Foundation\Console\Kernel->handle(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#15 {main}  

What am I doing wrong?

Cannot instantiate abstract class App\Http\Request\Request

Hello guys,

I have been trying to generate my doc but this error appear and I don't know why the error occurs on AbstractGenerator.php on line 144

Customize without *.md

Hi, great package. It's possible to customize the generated documentation without modify .md???

dingo response

I think here is missing '->getContent()' at the end to get the json response.

https://github.com/mpociot/laravel-apidoc-generator/blob/master/src/Mpociot/ApiDoc/Generators/DingoGenerator.php#L22

Optional Controller Doc Blocks override URI information

Hello there,

I'm currently facing an issue regarding the rendering of short descriptions of controller methods.
If you do not specify any description, the URI gets rendered as a routes title. This is totally fine. But if you put in a short description, the URI is not displayed in the title section or side bar at all.

See resources/views/partials/route.blade.php:

// ...
@if($parsedRoute['title'] != '')## {{ $parsedRoute['title']}}
@else## {{$parsedRoute['uri']}}
// ...

In my opinion, it would be better to display the routes URI here, regardless of the title being set.

Also, the current implementation displays a routes short description in the side bar if present. Wouldn't it be better to always display the routes URI, since the description rarely fits in here?

To be more specific: what I'm suggesting is to always display a routes URI as its title, and any controller method documentation optionally.

This could be achieved by changing resources/views/partials/route.blade.php to look like this

// ...
## {{$parsedRoute['uri']}}
@if($parsedRoute['title'] != '')__{{ $parsedRoute['title'] }}__
@endif
@if($parsedRoute['description'])

{!! $parsedRoute['description'] !!}
@endif
// ...

Any thoughts on this suggestion?
Maybe it would be a good idea to introduce a CLI option to enable this behavior, as this would be a breaking change.

Postman collection with URL different to localhost

Hello,

I wonder if there is any way to change the url shown in the Postman collection automatically generated, it always shows localhost even if I change my APP_URL env variable

Thanks :)

No bindings when getting route rules

In AbstractGenerator we are getting the route rules in getRouteRules() to use in the route parameters description in the docs.

This is basically just finding what request class the controller method is using, for instance UpdateFooRequest, then newing up an object of that class and calling rules() on it.

This crashes the API generation on my end because I am using a route variable for uniqueness validation. For instance, when calling PATCH /api/users/5, the email variable I am sending should be unique when updating user records, but the unique rule should not check user with id 5, because that's the one we are updating. I am getting the number 5 from the request class by using $this->userid.

Generating the docs I am passing --bindings=userid,1 which works fine for getting example data for the documentation, but the bindings are not carried over when newing up the request class to get the rules to generate the request validation rules descriptions.

Package windwalker/registry is abandoned

When installing the latest version of your plugin, I get this warning:

Package windwalker/registry is abandoned, you should avoid using it. Use windwalker/structure instead.

Greetings

Add support for auth driver while using Laravel Passport

Wanted to use this with Laravel Passport... but it doesn't seem to be working... I get like one or two "Processed route: ..." sentences, then it fails while trying to get the authenticated user's id... any ideas?

i'm referencing the auth driver inside of a FormRequest like:

$this->user('api')->getKey();

Error is:

Call to a member function getKey() on string

Proposal: Automatically generate Postman collections to use in Postman

I thought that it might be a nice addition to generate Postman collections, which can then be imported into Postman, to use them for testing purposes.

The API documentation could then show a "Add to Postman" button or similar, which links to the collection file.

What do you think about it?

https://www.getpostman.com/docs/collections

Expected a string. Got: boolean

Hi there,

Installed dev-master because 1.2 did not want to install

 Problem 1
    - Conclusion: don't install mpociot/laravel-apidoc-generator 1.2.3
    - Conclusion: don't install mpociot/laravel-apidoc-generator 1.2.2
    - Conclusion: don't install mpociot/laravel-apidoc-generator 1.2.1
    - Conclusion: remove phpdocumentor/reflection-docblock 3.0.2
    - Installation request for mpociot/laravel-apidoc-generator ^1.2 -> satisfiable by mpociot/laravel-apidoc-generator[1.2.0, 1.2.1, 1.2.2, 1.2.3].
    - Conclusion: don't install phpdocumentor/reflection-docblock 3.0.2
    - mpociot/laravel-apidoc-generator 1.2.0 requires phpdocumentor/reflection-docblock ~2.0 -> satisfiable by phpdocumentor/reflection-docblock[2.0.0, 2.0.1, 2.0.2, 2.0.3, 2.0.4].
    - Can only install one of: phpdocumentor/reflection-docblock[2.0.0, 3.0.2].
    - Can only install one of: phpdocumentor/reflection-docblock[2.0.1, 3.0.2].
    - Can only install one of: phpdocumentor/reflection-docblock[2.0.2, 3.0.2].
    - Can only install one of: phpdocumentor/reflection-docblock[2.0.3, 3.0.2].
    - Can only install one of: phpdocumentor/reflection-docblock[2.0.4, 3.0.2].
    - Installation request for phpdocumentor/reflection-docblock (locked at 3.0.2) -> satisfiable by phpdocumentor/reflection-docblock[3.0.2].

And now I get this:

  [InvalidArgumentException]       
  Expected a string. Got: boolean  

Add feature to register own Validator

Hello,

We created our own validator with its own set of rules, but I cannot see a way to register them to parse the rules.

It would be nice to be able to register the validator with the expected value and a "fake" value to be used for the request.

Annotation Proposals

Hey @mpociot ,

I have a few proposals for your package.
I thought about adding annotations to Controller Classes or respective methods in order to enrich the expressiveness of the documentation..

General

• Authentication Required: Is it possible to add a bootstrap label to each method name, if the route requires an authentication? For example a red label authentication required, if the user needs to be authenticated.
• Can we put the HTTP Request Methods (GET, POST, ...) in the sidebar on the left in order to show additional information?

What do you think about these annotations?

Controllers

• @group Test: Assigns all methods in this controller to the group Test (instead of @resource which is currently used, in order to avoid conflicts?)
• @authentication true | false: Shows the "authentication required" flag (e.g., if it is not possible to extract it from the router specified).

Methods

• @group Test: Assigns this method to the group Test (may overwrite the controllers group).
• @transformsTo Transformer: Specifies the Transformer which is used (see #43)
• @transient (or @ignore): Ignore this route for the docs (instead of using @hideFromAPIDocumentation
• @authentication true | false: Shows the "authentication required" flag (e.g., if it is not possible to extract it from the router specified). (may override the controllers authentication flag)
• @throws X | Y | Z: This methods throws the Exceptions X, Y or Z (or all of them ;) )
• @request FILENAME: Path to a file containing an example request
• @response FILENAME: Path to a file containing an example request (maybe we can solve the transformer issue this way?!)

Maybe some of these proposals would make a contribution to your package?
I would be glad to help you out, although I am no expert on creating / designing annotations and I surely would need some time to get familiar with the implementation and so on.. Anyways, I would be willing to contribute ;)

I will update this issue if I have additional ideas,..

Cheers

validation & examples

rules() contain:

'time_to' => 'required|date_format:H:i', and in example request show "time_from": "ex",
'notification_before' => 'integer|nullable|max:240', and in example request show "notification_before": 4782, (4782>240)

Response from Collection of objects.

First thanks for this useful tool ;)

I am trying to generate the response content from a endpoint of a Dingo API.
My endpoint return this format:

Illuminate\Support\Collection {#1234
  #items: array:3 [
    0 => Api\Entities\Content{#1243
      #id: 1
      #description: "Test A"
    }
    1 => Api\Entities\Content{#1247
      #id: 2
      #description: "Test B"
    }
    2 => Api\Entities\Content{#1246
      #id: 3
      #description: "Test C"
    }
  ]
}

laravel-apidoc-generator supports response like this? or only simple array? I am getting empty response.

Thanks

concerning the description of parameter

Would you please tell about how I can define the description of parameters by myself?

Lumen support?

Hey thanks for the package. Is it possible to use (compatible) with Lumen?

Cant Use "composer require mpociot/laravel-apidoc-generato" to Install

Hello, I have some problem when I use composer to install package. Can give some help? thanks.
Its seem version problem?

The error message is：

Your requirements could not be resolved to an installable set of packages.

Problem 1
- Installation request for mpociot/laravel-apidoc-generator ^1.3 -> satisfiable by mpociot/laravel-apidoc-generator[1.3.0].
- Conclusion: don't install phpdocumentor/reflection-docblock 3.0.3
- mpociot/laravel-apidoc-generator 1.3.0 requires phpdocumentor/reflection-docblock ^2.0 -> satisfiable by phpdocumentor/reflection-docblock[2.0.4, 2.0.0, 2.0.1, 2.0.2, 2.0.3].
- Can only install one of: phpdocumentor/reflection-docblock[3.0.3, 2.0.4].
- Can only install one of: phpdocumentor/reflection-docblock[2.0.0, 3.0.3].
- Can only install one of: phpdocumentor/reflection-docblock[2.0.1, 3.0.3].
- Can only install one of: phpdocumentor/reflection-docblock[2.0.2, 3.0.3].
- Can only install one of: phpdocumentor/reflection-docblock[2.0.3, 3.0.3].
- Can only install one of: phpdocumentor/reflection-docblock[2.0.4, 3.0.3].
- Installation request for phpdocumentor/reflection-docblock (locked at 3.0.3) -> satisfiable by phpdocumentor/reflection-docblock[3.0.3].

Installation failed, reverting ./composer.json to its original content.

/** tag not working, /* yes

Given this login method:

/**
 *  API Login, on success return JWT Auth token
 *
 * @param \Illuminate\Http\Request $request
 *
 * @return \Illuminate\Http\JsonResponse
 */
public function login(Request $request)
{
    // grab credentials from the request
    $credentials = $request->only('email', 'password');
    try {
        // attempt to verify the credentials and create a token for the user
        if (!$token = JWTAuth::attempt($credentials)) {
            return response()->json(['error' => 'invalid_credentials'], 401);
        }
    } catch (JWTException $e) {
        // something went wrong whilst attempting to encode the token
        return response()->json(['error' => 'could_not_create_token'], 500);
    }

    // all good so return the token
    return response()->json(compact('token'));
}

When I run the command php artisan api:generate --router="dingo" --routePrefix="v1" I get the following exception:

[2016-06-20 20:40:32] local.INFO: App\Http\Controllers\v1\SessionsController@login  
[2016-06-20 20:40:32] local.ERROR: exception 'Symfony\Component\Debug\Exception\FatalErrorException' with message 'Call to undefined method phpDocumentor\Reflection\DocBlock::getShortDescription()' in /vagrant/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/Generators/AbstractGenerator.php:104
Stack trace:
#0 /vagrant/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(133): Symfony\Component\Debug\Exception\FatalErrorException->__construct()
#1 /vagrant/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(118): Illuminate\Foundation\Bootstrap\HandleExceptions->fatalExceptionFromError()
#2 /vagrant/vendor/laravel/framework/src/Illuminate/Foundation/Bootstrap/HandleExceptions.php(0): Illuminate\Foundation\Bootstrap\HandleExceptions->handleShutdown()
#3 /vagrant/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/Generators/DingoGenerator.php(29): Mpociot\ApiDoc\Generators\AbstractGenerator->getRouteDescription()
#4 /vagrant/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php(200): Mpociot\ApiDoc\Generators\DingoGenerator->processRoute()
#5 /vagrant/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php(74): Mpociot\ApiDoc\Commands\GenerateDocumentation->processDingoRoutes()
#6 /vagrant/vendor/laravel/framework/src/Illuminate/Container/Container.php(507): Mpociot\ApiDoc\Commands\GenerateDocumentation->handle()
#7 /vagrant/vendor/laravel/framework/src/Illuminate/Container/Container.php(507): call_user_func_array:{/vagrant/vendor/laravel/framework/src/Illuminate/Container/Container.php:507}()
#8 /vagrant/vendor/laravel/framework/src/Illuminate/Console/Command.php(169): Illuminate\Container\Container->call()
#9 /vagrant/vendor/symfony/console/Command/Command.php(256): Illuminate\Console\Command->execute()
#10 /vagrant/vendor/laravel/framework/src/Illuminate/Console/Command.php(155): Symfony\Component\Console\Command\Command->run()
#11 /vagrant/vendor/symfony/console/Application.php(791): Illuminate\Console\Command->run()
#12 /vagrant/vendor/symfony/console/Application.php(186): Symfony\Component\Console\Application->doRunCommand()
#13 /vagrant/vendor/symfony/console/Application.php(117): Symfony\Component\Console\Application->doRun()
#14 /vagrant/vendor/laravel/framework/src/Illuminate/Foundation/Console/Kernel.php(107): Symfony\Component\Console\Application->run()
#15 /vagrant/artisan(36): Illuminate\Foundation\Console\Kernel->handle()
#16 /vagrant/artisan(0): {main}()
#17 {main}  

If I put /** instead of /* it gives this error -> see #46

JWT Authentication

Dear @mpociot and others,

I am using JWT Authentication (see this package in order to secure my API. However, when generating the API Documentation using your package, the request and response for these routes are empty (or null).

I try running the --actAsUserId=1 parameter as well - didn`t change anything. Could it be, because my JWT plugin requires atoken parameter? Or am I (again) missing something out?

Thanks you very much in advance ;)

[Ramsey\Uuid\Exception\UnsatisfiedDependencyException]

I've tryed v.1.6.4 and 1.6.3 and it's the same error.

[Ramsey\Uuid\Exception\UnsatisfiedDependencyException]

When calling Ramsey\Uuid\Converter\Time\DegradedTimeConverter::calculateTime on a 32-bit system, Moontoast\Math\BigNumber must be present.

Anyone has passed through this?

Thanks.

Console Feedback "Expected a string. Got: boolean"

Thanks for your great job.
I found a little problem on generating docs.
My code is below

routes.php

Route::group(['middleware' => 'api'], function () {
    Route::post('/get-app-token', 'AppAuthController@getToken')->name('getToken');
}); 

AppAuthController.php

use App\Http\Requests\getTokenAPI;
public function getToken(getTokenAPI $request)
    {
          //do something
    }

Form Validation Requests

public function rules()
    {
        return [
            'name' => 'required|alpha_num|unique:users|between:3,20',
            'password' => 'required|alpha_num|max:20',
            'hospital_id' => 'required|numeric|max:5'
        ];
    }

Console
I tried to generate doc with route name on my windows local console:
{lamb} php artisan api:gen --routes="getToken"

[InvalidArgumentException]
Expected a string. Got: boolean

And I got error log as attached.
Is there any setting I missed?
Thanks for your time to help.

laravel.txt

Bindings Command-Argument

When I try to add bindings in order to auto-generate responses, I use the following command
php artisan api:generate --routePrefix="v1" --router="Dingo" --bindings=faq,1|tip,1
to use the Faq and Tip with ID 1
(as described here:

bindings - List of route bindings that should be replaced when trying to retrieve route results.
Syntax format: binding_one,id|binding_two,id

)

However, when executing the command, I get the following error:
The command 'tip' is either misspelled or could not be found.

Greetings

[Proposal] Navigation split up by Resource

I am currently working on a PR which makes it possible to group the navigation by resource. To do this you need to define a @resource annotation on top of a controller which will be used as a categiory for all methods inside of the controller.

Would the @resource annotation be fine for this or should something else be used?

Controller

<?php

namespace App\Http\Controllers;

/**
 * @resource Invoices
 */
class InvoiceController extends Controller
{
    ///
}

Result

Dingo/API closure problem

Hi,
There is a problem when you try to use a closure in your routes file like this example:
$api->get('/', function() { return ['test' => 'test']; });

this closure will break the docs generation and show this error:
[ErrorException] explode() expects parameter 2 to be string, object given

Allow multiple generate calls without loosing modifications to index.md

Right now, if you want to modify the generated API documentation, you will need to open the index.md file and change whatever you need.
Later on, you can call api:update and your documentation will be refreshed.

But if at a later point, you add a new API route and call api:generate again, your existing modifications to the documentation will be lost.

We can avoid this by adding simple HTML comments with a route identifier around the documentation blocks: <!-- route_identifier -->

The markdown generation would need to be modified.

Any help is greatly appreciated.

/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php on line 221

"laravel/framework": "5.2.*",
"jenssegers/mongodb" : "^3.0",

After using param --actAsUserId=1 I get error like this

[Symfony\Component\Debug\Exception\FatalThrowableError]                                                                          
  Type error: Argument 1 passed to Illuminate\Auth\SessionGuard::setUser() must implement interface Illuminate\Contracts\Auth\Aut  
  henticatable, null given, called in /app/vendor/mpociot/laravel-apidoc-generator/src/Mpociot/ApiDoc/Commands/GenerateDocumentation.php on line 221  

The answer is to convert $actAs to int, because Mongodb read this like string

if (! empty($actAs)) {
            if (version_compare($this->laravel->version(), '5.2.0', '<')) {
                $userModel = config('auth.model');
                $user = $userModel::find((int) $actAs);
                $this->laravel['auth']->setUser($user);
            } else {
                $userModel = config('auth.providers.users.model');
                $user = $userModel::find((int) $actAs);
                $this->laravel['auth']->guard()->setUser($user);
            }
        }

The command defined in "Mpociot\ApiDoc\Commands\GenerateDocumentation" cannot have an empty name.

After installer, and run command "$ php artisan api:generate --routePrefix="api/v1/*" show this error, then run composer update and the same error

laravel-apidoc-generator ignore the transformers during docs generation

laravel-apidoc-generator ignore the transformers during docs generation
look at the response in following screen shot and notice how delicious is 1:

but if I use Postman, the delicious is displayed correctly as true:

here's the code that generates the response:

public function show($id)
    {
        $fruit = Fruit::where('id', $id)->first();

        if ($fruit) {
            return $this->item($fruit, new FruitsTransformer);
        }

        return $this->response->errorNotFound();
    }

and the full code can be found at:
https://github.com/devmatic/fruits-api/

Array Validation L5.1

Dear all,
first of all - thanks for the plugin. Currently, I am evaluating if this plugin suits my needs for documenting the API I am currently building.

When running the command
php artisan api:generate --routePrefix="v1" --router="Dingo"
i managed to generate documentation.

However, it fails on a specific POST route, which uses Array Validations for the request. Note, that I am using Laravel 5.1, which does not support Array Validations out of the box (L5.2 however, does).

Therefore, I am using this piece of code as a Validation Request:

public function rules() {
   $rules = [
      "data" => "required",
      "data.type" => "required",
      "data.attributes" => "required",

      "data.attributes.name" => "required | max:255",

      "data.attributes.translations" => "array",
   ];

   // loop through the translations
   foreach($this->input("data.attributes.translations") as $key => $value) {
   $rules["data.attributes.translations." . $key . ".locale"] = "required";
   $rules["data.attributes.translations." . $key . ".title"] = "required|max:255";
}

return $rules;

This would, for example, evaluate the following JSON body as valid:

{
   "data" : {
      "type" : "tips",
      "attributes" : {
         "name" : "internal name",
         "translations" : [
            {
               "locale" : "en",
               "title" : "EN title"
            }, {
               "locale" : "de",
               "title" : "DE title"
            }, {
               "locale" : "fr",
               "title" : "FR title"
            }
         ]
      }
   }
}

However, when running the command above, I get the following error:

  [ErrorException]
  Invalid argument supplied for foreach()

which directly correlates with the foreach() statement in my validation class.

I am aware of issue #52 , however, this issue deals with L5.2. specific "array validations" (e.g., you can write validations like this: data.attributes.translations.*.locale = required (notice the * used as a wildcard).

Does somebody have a solution for my problem?
Greetings and Cheers

[Ramsey\Uuid\Exception\UnsatisfiedDependencyException]

`D:\WWW\oauth>php artisan api:generate --routePrefix=v1/*
Wrote index.md to: public/docs
Generating API HTML code
Wrote HTML documentation to: public/docs/public/index.html
Generating Postman collection

[Ramsey\Uuid\Exception\UnsatisfiedDependencyException]
When calling Ramsey\Uuid\Converter\Time\DegradedTimeConverter::calculateTime on a 32-bit system, Moontoast\Math\Big
Number must be present.`
I use win10 64-bit system, What does this exception mean?

Dingo/API support

Thank for this great tool! I noticed that routes created by the Dingo/API package are not generating any documentation. Looks like this is not supported, so I would like to request for support of those routes to be documented as well :)

Can't parse array validation rules?

Seems as if the rules parser is unable to parse rules as the ones described here: https://laravel.com/docs/5.2/validation#validating-arrays

For instance users.*.email.

At least these do not show up in my parameters list in the generated documentation at all.