README

Biblioteca PHP para Laravel que exporta automaticamente rotas da aplicação para Postman Collections v2.1, incluindo validações, body examples, autenticação e responses organizados por prefixo de rota.

🚀 Características

✅ Extração automática de validações do FormRequest
✅ Geração de body examples baseados em regras de validação
✅ Detecção automática de autenticação via middlewares
✅ Organização inteligente por prefixos de rota
✅ Responses de exemplo (200, 422, 401)
✅ Variáveis de ambiente configuráveis
✅ Path variables automáticos para parâmetros de rota
✅ Headers padrão (Accept, Content-Type, Authorization)
✅ 100% compatível com Postman Collection v2.1

📋 Requisitos

PHP 8.1 ou superior
Laravel 10.x, 11.x, 12.x ou 13.x

📦 Instalação

Instale o pacote via Composer:

composer require silvio-batista/laravel-postman-exporter --dev

Publique o arquivo de configuração:

php artisan vendor:publish --provider="LaravelPostmanExporter\PostmanExporterServiceProvider"

Isso criará o arquivo config/postman-exporter.php.

🎯 Uso Básico

Exportar todas as rotas

php artisan postman:export

O arquivo será salvo em storage/postman-collection.json.

Opções de linha de comando

# Especificar caminho de saída customizado
php artisan postman:export --output=public/api-docs.json

# Definir nome customizado da collection
php artisan postman:export --name="My API v1"

# Filtrar rotas por padrão
php artisan postman:export --routes="api/*"

# Excluir rotas específicas
php artisan postman:export --exclude="admin/*"

# Combinar opções
php artisan postman:export --output=api.json --name="My API" --routes="api/*"

⚙️ Configuração

O arquivo config/postman-exporter.php permite personalizar diversos aspectos:

return [
    // Nome padrão da collection
    'collection_name' => env('APP_NAME', 'Laravel API'),
    
    // URL base padrão
    'base_url' => env('APP_URL', 'http://localhost'),
    
    // Prefixos de rotas a incluir (null = todas)
    'route_prefix' => ['api'],
    
    // Padrões de rotas a excluir
    'exclude_routes' => [
        '_debugbar/*',
        'telescope/*',
        'horizon/*',
        'sanctum/csrf-cookie',
    ],
    
    // Incluir responses de exemplo
    'include_responses' => true,
    
    // Incluir testes de exemplo (scripts Postman)
    'include_tests' => false,
    
    // Organização dos folders: 'prefix', 'controller', 'middleware'
    'organize_by' => 'prefix',
    
    // Middlewares que indicam autenticação
    'auth_middlewares' => ['auth', 'auth:sanctum', 'auth:api'],
    
    // Headers padrão
    'default_headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    
    // Variáveis de ambiente
    'variables' => [
        'base_url' => env('APP_URL', 'http://localhost'),
        'auth_token' => '',
    ],
];

📚 Exemplo Completo

1. Rotas Laravel

// routes/api.php
Route::prefix('api')->group(function () {
    Route::get('/users', [UserController::class, 'index']);
    Route::post('/users', [UserController::class, 'store']);
    Route::get('/users/{id}', [UserController::class, 'show']);
    
    Route::middleware('auth:sanctum')->group(function () {
        Route::put('/users/{id}', [UserController::class, 'update']);
        Route::delete('/users/{id}', [UserController::class, 'destroy']);
    });
});

2. FormRequest com validações

// app/Http/Requests/StoreUserRequest.php
class StoreUserRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'email', 'unique:users'],
            'password' => ['required', 'string', 'min:8'],
            'age' => ['nullable', 'integer', 'min:18'],
            'tags' => ['array', 'min:1'],
        ];
    }
}

3. Controller

// app/Http/Controllers/UserController.php
class UserController extends Controller
{
    public function store(StoreUserRequest $request)
    {
        $user = User::create($request->validated());
        return response()->json($user, 201);
    }
}

4. Exportar

php artisan postman:export

5. Resultado no Postman

A collection gerada terá:

Folder: Users

GET Get Users

POST Create Users (com body example automático)

{
  "name": "John Doe",
  "email": "user@example.com",
  "password": "password123",
  "age": 18,
  "tags": ["tag1"]
}

GET Get Users Id
PUT Update Users Id (requer autenticação)
DELETE Delete Users Id (requer autenticação)

Variáveis:

base_url: http://localhost
auth_token: (vazio - configure após importar)

Responses de exemplo:

200 OK (sucesso)
422 Unprocessable Entity (erro de validação)
401 Unauthorized (não autenticado)

🎨 Recursos Avançados

Detecção Automática de Tipos

O parser detecta automaticamente o tipo de cada campo:

'email' => ['required', 'email']           // → "user@example.com"
'url' => ['url']                           // → "https://example.com"
'date' => ['date']                         // → "2024-01-15"
'is_active' => ['boolean']                 // → true
'price' => ['numeric', 'min:0']            // → 0
'status' => ['in:active,inactive']         // → "active"

Organização Flexível

Organize suas requests por:

// Por prefixo de rota (padrão)
'organize_by' => 'prefix',  // api/users, api/posts

// Por controller
'organize_by' => 'controller',  // UserController, PostController

// Por middleware
'organize_by' => 'middleware',  // auth, guest, admin

Path Variables

Parâmetros de rota são convertidos automaticamente:

Route::get('/users/{id}/posts/{postId}', ...);
// Gera: /users/{{id}}/posts/{{postId}}

Autenticação

Middlewares de autenticação são detectados automaticamente:

Route::middleware('auth:sanctum')->group(function () {
    // Headers gerados automaticamente:
    // Authorization: Bearer {{auth_token}}
});

📤 Importando no Postman

Abra o Postman
Clique em Import no canto superior esquerdo
Selecione o arquivo postman-collection.json
Configure as variáveis:
- base_url: URL da sua API (ex: https://api.example.com)
- auth_token: Token de autenticação (se necessário)
Pronto! Todas as rotas estão disponíveis para teste

🧪 Testes

composer test

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
Commit suas mudanças (git commit -m 'Add some AmazingFeature')
Push para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

📝 Licença

Este projeto está licenciado sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🙏 Agradecimentos

Comunidade Laravel
Postman API Platform
Todos os contribuidores

📧 Suporte

Se você encontrar algum problema ou tiver sugestões, por favor:

Verifique as Issues existentes
Crie uma nova Issue descrevendo o problema ou sugestão
Forneça exemplos e contexto quando possível

🌟 Star o Projeto

Se este pacote foi útil para você, considere dar uma ⭐️ no GitHub!

Feito com ❤️ para a comunidade Laravel

silvio-batista / laravel-postman-exporter

Maintainers

Package info

Statistics

Security