README

Elegan é um pacote desenvolvido para padronizar a documentação de rotas em projetos Laravel. Ele permite a criação de arquivos de documentação no formato .yaml diretamente via terminal.

Foi projetado para uso com o Laravel e é baseado no pacote L5-Swagger.

Instalação

Execute o seguinte comando no terminal:

$ composer require labi9/elegan

Depois, publique os arquivos necessários:

$ php artisan vendor:publish --provider "Labi9\Elegan\EleganServiceProvider"

🚀 Acessando a Documentação

Após a instalação, acesse a URL:

$ http://127.0.0.1:8000/api/docs

⚙️ Configurações

Configuração de Rota

Altere o caminho de acesso à documentação no arquivo config/elegan.php:

// config/elegan.php

'routes' => [
  'api' => 'novo/caminho'
]

Protegendo o Acesso

Para que seja possível utilizar este recurso, a tabela sessions do Laravel precisa existir no banco de dados

Adicione a rota ao routes/web.php:

// routes/web.php

Route::view('/access-docs', 'elegan::docs')->name('access-docs');

A documentação só se tornará privada quando a variável ELEGAN_KEY for definida na .env

Limite de Requisições

Este recurso é somente habilitado quando a proteção de acesso à documentação estiver ativa

O limite máximo de requisições por minuto e o tempo de timeout podem ser ajustados no arquivo de configuração config/elegan.php.

// config/elegan.php

'rate_limit' => 10,
'decay_minutes' => 1,

📄 Arquivos de rota

Cada Action representa um tipo de operação REST:

Action	Método HTTP
`index`	GET
`show`	GET
`store`	POST
`update`	PUT
`destroy`	DELETE

Os nomes das Actions podem ser personalizados no arquivo config/elegan.php. Cada Action possui sua configuração base de arquivo.

🛠️ Comandos

Crie os arquivos de documentação usando os comandos abaixo:

Comandos individuais

php artisan docs:route example store cria apenas o arquivo store.
php artisan docs:route example index cria apenas o arquivo index.
php artisan docs:route example show cria apenas o arquivo show.
php artisan docs:route example update cria apenas o arquivo update.
php artisan docs:route example destroy cria apenas o arquivo destroy.

Referência no seu arquivo .yaml:

# index.yaml

paths:
  /caminhoDaRota:
    $ref: routes/example/actions.yaml

Observação: o nome actions.yaml pode ser alterado no arquivo config/elegan.php.

Parâmetros

Para adicionar parâmetros à rota, inclua o caractere ":" seguido pelo nome do parâmetro. É possível adicionar mais de um parâmetro na mesma rota.

Quando um parâmetro é adicionado, ele é automaticamente incluído na action correspondente. Por exemplo, para adicionar um parâmetro "id" na rota "example" e a action "show", utilize o comando abaixo:

# show.yaml

php artisan docs:route example/:id show

A estrutura de pastas para essa rota seria a seguinte:

example/
  └── id/
      ├── actions.yaml
      └── show.yaml

O parâmetro "id" é adicionado automaticamente ao arquivo show.yaml, como mostrado abaixo:

parameters:
  - in: path
    name: id
    schema:
      type: string
    required: true
    description: ''

Autenticação:

Adicione o parâmetro --auth para incluir a obrigatoriedade do token de acesso:

php artisan docs:route example show --auth

Referência no seu arquivo .yaml:

# show.yaml

security:
  - bearerAuth: []

Comando completo

php artisan docs:route example/:id index show store update destroy --auth`

Estrutura de saída:

example/
  └── id/
      ├── actions.yaml
      ├── index.yaml
      ├── store.yaml
      ├── show.yaml
      ├── update.yaml
      └── destroy.yaml

Observações

Não é possível ter duas actions com o mesmo método HTTP (por exemplo, index e show, ambos utilizam o método GET) no mesmo arquivo actions.yaml. Eles precisam estar em arquivos separados.

🧱 Actions e Suas Funções

Action	Método HTTP	Descrição
`index`	GET	Retorna uma listagem paginada
`show`	GET	Exibe os detalhes de um item
`store`	POST	Cria um novo item com exemplos de requisição e código de status 201
`update`	PUT	Atualiza um item com exemplos de requisição e código de status 204
`destroy`	DELETE	Remove um item do banco de dados

As validações da requisição devem ser adicionadas manualmente para as actions store e update, assim como os exemplos de retorno das actions index e show.

Renomeando arquivos

$ php artisan docs:route example/:id store --name=login

Ou múltiplos nomes:

$ php artisan docs:route example/:id store show --name=login --name=me

A ordem dos --name= deve seguir a ordem das actions.

Se o nome não é informado, o arquivo ficará com o nome da action correspondente.

🗒️ Notas de atualização

Crie o histórico da documentação com:

$ php artisan docs:note nome

Especificar múltiplas rotas:

$ php artisan docs:note nome --routes=2

✅ Requisitos

Laravel - Versão 12 ou superior

labi9 / elegan

Maintainers

Details