Gerando uma documentação usando o plugin laravel-apidoc-generator

apidoc-generator.md

exemplo de documentação que dá pra gerar: http://marcelpociot.de/whiteboard/

Instalando o plugin

cd pasta/do/projeto

composer require mpociot/laravel-apidoc-generator

No arquivo config/app.php adicionar o provider:

Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class,

Gerando a documentação

php artisan api:generate --routePrefix="*"

Ele gera a documentação com base nos comentários no estilo DocBlock

Notas

Coisas que fizeram diferença pra mim durante a implementação

@resource nas classes dos Controllers

Para agrupar as rotas no menu, ele usa a marcação do @resource no controller. Isso evita que a documentaço fique uma bagunça com todas as rotas listadas uma depois da outra.

Exemplo:

/**
 * @resource Home
 *
 * Home
 */
class HomeController extends Controller
{
  ...
}

Autorização

Na hora de gerar algumas rotas o exemplo de retorno fica com um erro de "Usuário não autenticado", para isso o comando de geração tem uma flag que permite usar algum usuário com permissão da rota. Para atuar como o usuário de id 1 por exemplo:--actAsUserId="1".

Vale a pena dar uma olhadinha no README do plugin para mais detalhes do que dá pra fazer.

Form Request Validation

Se o projeto estiver usando Form Request Validation os paramêtros que são recebidos pelas rotas já ficam bonitinhos. :sparkles: