📜 Gandalf-Swagger

🚀 Gandalf-Swagger é um pacote para Laravel que gera automaticamente a documentação da API utilizando Swagger (OpenAPI 3.0) com atributos PHP (#[Attribute]).

---

⚡ Recursos

✅ Geração automática de documentação Swagger baseada em atributos PHP
✅ Suporte ao Laravel 11.x
✅ Cache configurável para melhorar performance
✅ Interface interativa via Swagger UI
✅ Fácil de instalar e configurar

---

📦 Instalação

1️⃣ Instalar via Composer

composer require gandalf/swagger

2️⃣ Publicar as configurações e views

php artisan vendor:publish --tag=swagger-config --force
php artisan vendor:publish --tag=swagger-views --force

---

🛠️ Configuração

🔹 Configurar o arquivo .env

Após a publicação, edite o arquivo .env para ajustar as configurações:

SWAGGER_TITLE="Minha API Customizada"
SWAGGER_VERSION="1.0.0"
SWAGGER_CACHE_TTL=300
SWAGGER_DOCS_PATH="/docs"
SWAGGER_JSON_PATH="/api/swagger.json"

🔹 Arquivo de Configuração (config/swagger.php)

Se necessário, altere as configurações diretamente no arquivo:

return [
    'title' => env('SWAGGER_TITLE', 'Minha API Customizada'),
    'version' => env('SWAGGER_VERSION', '1.0.0'),
    'cache_ttl' => env('SWAGGER_CACHE_TTL', 300),
    'docs_path' => env('SWAGGER_DOCS_PATH', '/docs'),
    'json_path' => env('SWAGGER_JSON_PATH', '/api/swagger.json'),
];

---

🚀 Como Usar

1️⃣ Adicione Atributos (#[Attribute]) nas Rotas

No seu Controller, adicione os atributos #[ApiRoute] e #[ApiResponse]:

use Gandalf\Swagger\Attributes\ApiRoute;
use Gandalf\Swagger\Attributes\ApiResponse;

class UserController extends Controller
{
    #[ApiRoute('GET', '/users', 'Lista todos os usuários')]
    #[ApiResponse(200, 'Lista de usuários retornada com sucesso')]
    public function index()
    {
        return response()->json([
            ['id' => 1, 'name' => 'João'],
            ['id' => 2, 'name' => 'Maria'],
        ]);
    }
}

2️⃣ Acesse a Documentação

Após adicionar os atributos, acesse a documentação interativa:

📌 Swagger UI: http://127.0.0.1:8000/docs
📌 Swagger JSON: http://127.0.0.1:8000/api/swagger.json

---

🎯 Exemplos Avançados

Definir múltiplos status de resposta

use Gandalf\Swagger\Attributes\ApiRoute;
use Gandalf\Swagger\Attributes\ApiResponse;

class AuthController extends Controller
{
    #[ApiRoute('POST', '/login', 'Autenticação do usuário')]
    #[ApiResponse(200, 'Usuário autenticado com sucesso')]
    #[ApiResponse(401, 'Credenciais inválidas')]
    public function login(Request $request)
    {
        return response()->json(['message' => 'Login realizado!']);
    }
}

---

⚙️ Como Funciona Internamente?

O Gandalf-Swagger usa reflexão (ReflectionClass) para escanear os controladores, identificar métodos anotados com #[ApiRoute], e gerar o JSON do Swagger automaticamente.

🔹 Atributos personalizados (#[ApiRoute], #[ApiResponse])
🔹 Cache para otimizar performance
🔹 Suporte completo ao Laravel

---

🛠️ Testes

Para rodar os testes unitários:

composer test

---

📜 Licença

Este projeto é licenciado sob a MIT License.

---

💡 Contribuição

1. Faça um fork do projeto
2. Crie uma branch (git checkout -b feature/nova-funcionalidade)
3. Faça commit das mudanças (git commit -m 'Adiciona nova funcionalidade')
4. Faça um push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request 🚀

---

📢 Contato & Suporte

📌 GitHub: andreunix
📌 Packagist: Gandalf-Swagger

🚀 Agora sua documentação está profissional e pronta para uso! 😃🔥