🇬🇧 English | 🇧🇷 Português

Laravel JWT Auth API

A RESTful API built with Laravel and JWT authentication, following best practices (SRP, DIP, DRY), automated tests, and endpoint documentation.

Features

• JWT Authentication
  • User registration
  • User login
  • User logout
  • JWT token refresh
• Route protection
  • auth:api middleware for protected routes
  • Custom middleware for header validation
• User management
  • List all users (protected route)
  • Get user by ID (protected route)
• Standardized responses
  • All responses follow a consistent pattern via HttpResponse
• Automated tests
  • Tests for registration, login, logout, refresh, and user listing
  • Coverage for success and error scenarios
• Endpoint documentation
  • RestClient.http file for easy endpoint testing

Architecture

• SRP (Single Responsibility Principle): Each service/controller has a single responsibility.
• DIP (Dependency Inversion Principle): Controllers depend on abstractions (services), making testing and maintenance easier.
• DRY (Don't Repeat Yourself): Logic and standardized responses are centralized in utility classes.

Endpoints

Method	Route	Protected	Description
POST	/api/register	No	Register a new user
POST	/api/login	No	Login and get JWT token
POST	/api/logout	Yes	Logout and invalidate token
POST	/api/refresh	Yes	Refresh JWT token
GET	/api/users	Yes	List all users
GET	/api/users/{id}	Yes	Get user by ID

Getting Started

1. Clone the repository

   git clone <url>
   cd laravel-jwt

2. Set up the environment

   • Copy .env.example to .env and adjust variables as needed.

3. Start Docker containers

   docker-compose up -d

4. Install dependencies and run migrations

   docker-compose exec app composer install
   docker-compose exec app php artisan migrate

5. (Optional) Seed the database

   docker-compose exec app php artisan db:seed

6. Run tests

   docker-compose exec app php artisan test

Testing Endpoints

• Use the app/Utils/RestClient.http file to easily test all endpoints (VSCode REST Client extension or Insomnia/Postman).
• Example for refreshing token:

  POST http://localhost/api/refresh
  Authorization: Bearer <your_token>
  Accept: application/json

Main Directory Structure

app/
  Http/
    Controllers/
      AuthController.php
    Middleware/
      ValidateHeaders.php
    HttpResponse.php
  Services/
    AuthService.php
    UserService.php
  Models/
    User.php
routes/
  api.php
tests/
  Feature/
    Auth/
      LoginTest.php
      LogoutTest.php
      RegisterTest.php
      RefreshTokenTest.php
    Users/
      ListUsersTest.php

Standards & Best Practices

• Semantic commits: Conventional Commits (feat, fix, refactor, test, etc)
• SOLID: Modular, testable, and maintainable code
• DRY: Centralized and reusable logic
• Tests: Coverage for all critical flows

Notes

• The project uses JWT for authentication, ensuring security and scalability.
• All protected routes require the header Authorization: Bearer <token>.
• The validate.headers middleware ensures requests accept JSON.

---

Laravel JWT Auth API

API RESTful desenvolvida em Laravel com autenticação JWT, seguindo boas práticas de arquitetura (SRP, DIP, DRY), testes automatizados e documentação de endpoints.

Funcionalidades

• Autenticação JWT
  • Registro de usuário
  • Login de usuário
  • Logout de usuário
  • Refresh de token JWT
• Proteção de rotas
  • Middleware auth:api para rotas protegidas
  • Middleware customizado para validação de headers
• Gestão de usuários
  • Listagem de todos os usuários (rota protegida)
  • Consulta de usuário por ID (rota protegida)
• Respostas padronizadas
  • Todas as respostas seguem um padrão consistente via HttpResponse
• Testes automatizados
  • Testes de registro, login, logout, refresh e listagem de usuários
  • Cobertura de cenários de sucesso e erro
• Documentação de endpoints
  • Arquivo RestClient.http para testar todos os endpoints facilmente

Arquitetura

• SRP (Single Responsibility Principle): Cada service/controller tem uma responsabilidade única.
• DIP (Dependency Inversion Principle): Controllers dependem de abstrações (services), facilitando testes e manutenção.
• DRY (Don't Repeat Yourself): Lógica e respostas padronizadas centralizadas em classes utilitárias.

Endpoints

Método	Rota	Protegida	Descrição
POST	/api/register	Não	Registro de novo usuário
POST	/api/login	Não	Login e geração de token JWT
POST	/api/logout	Sim	Logout e invalidação do token
POST	/api/refresh	Sim	Refresh do token JWT
GET	/api/users	Sim	Listar todos os usuários
GET	/api/users/{id}	Sim	Buscar usuário por ID

Como rodar o projeto

1. Clone o repositório

   git clone <url>
   cd laravel-jwt

2. Configure o ambiente

   • Copie .env.example para .env e ajuste as variáveis conforme necessário.

3. Suba os containers Docker

   docker-compose up -d

4. Instale as dependências e rode as migrations

   docker-compose exec app composer install
   docker-compose exec app php artisan migrate

5. (Opcional) Popule o banco com seeders

   docker-compose exec app php artisan db:seed

6. Testes

   docker-compose exec app php artisan test

Testando os endpoints

• Utilize o arquivo app/Utils/RestClient.http para testar todos os endpoints facilmente (VSCode com extensão REST Client ou Insomnia/Postman).
• Exemplo de uso do refresh token:

  POST http://localhost/api/refresh
  Authorization: Bearer <seu_token>
  Accept: application/json

Estrutura dos principais diretórios

app/
  Http/
    Controllers/
      AuthController.php
    Middleware/
      ValidateHeaders.php
    HttpResponse.php
  Services/
    AuthService.php
    UserService.php
  Models/
    User.php
routes/
  api.php
tests/
  Feature/
    Auth/
      LoginTest.php
      LogoutTest.php
      RegisterTest.php
      RefreshTokenTest.php
    Users/
      ListUsersTest.php

Padrões e Boas Práticas

• Commits semânticos: Conventional Commits (feat, fix, refactor, test, etc)
• SOLID: Código modular, testável e de fácil manutenção
• DRY: Lógica centralizada e reutilizável
• Testes: Cobertura para todos os fluxos críticos

Observações

• O projeto utiliza JWT para autenticação, garantindo segurança e escalabilidade.
• Todas as rotas protegidas exigem o header Authorization: Bearer <token>.
• O middleware validate.headers garante que as requisições aceitem JSON.

---

⭐️ If you liked this project, give it a star on GitHub! ⭐️
github.com/NatanR-dev/laravel-jwt

_{Open source project. Contributions are welcome!}