Una API de ejemplo desarrollada con Spring Boot que demuestra una arquitectura por capas con patrones genéricos y generación automática de código CRUD.
- Java 21 - Lenguaje de programación
- Spring Boot 3.5.2 - Framework principal
- PostgreSQL - Base de datos
- Liquibase - Migraciones de base de datos
- SpringDoc OpenAPI - Documentación automática de API
- Gradle - Gestión de dependencias y construcción
- Docker & Docker Compose - Containerización
- PMD - Análisis estático de código
- Java 21+
- PostgreSQL
- Docker (opcional)
- Task - Para comandos automatizados
- Bun - Para generadores de código
git clone https://github.com/joalvarezdev/simple-example-api
cd simple-example-apiCrear un archivo .env en la raíz del proyecto:
DATABASE_URL=jdbc:postgresql://localhost:5432/simple-example-api DATABASE_USERNAME=postgres DATABASE_PASSWORD=postgres CONTEXT_PATH=/
# Usando Docker
docker run --name postgres-simple-api -e POSTGRES_DB=simple-example-api -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:15o
# Usando Docker Compose
docker compose up -d./gradlew bootRun
# Construir la aplicación task build # Construir imagen Docker task docker-build APP_NAME=simple-example-api # Generar código CRUD task entity
La aplicación estará disponible en: http://localhost:8090
Este proyecto incluye un sistema de generadores de código usando Plop.js que permite crear componentes CRUD completos.
- Controller - Controladores REST
- Service - Servicios de negocio
- DAO - Objetos de acceso a datos
- DTO - Objetos de transferencia de datos
- Domain - Entidades de dominio
- Repository - Repositorios JPA
- Mapper - Mapeadores entre capas
task entity
# Seguir las instrucciones interactivas para generar el códigosrc/main/java/com/joalvarez/simpleexampleapi/
├── config/ # Configuraciones de Spring
├── controller/ # Controladores REST
│ └── general/ # Controladores base y genéricos
├── data/ # Capa de datos
│ ├── dao/ # Data Access Objects
│ ├── dto/ # Data Transfer Objects
│ ├── mapper/ # Mapeadores entre capas
│ └── repository/ # Repositorios JPA
├── exception/ # Manejo de excepciones
├── service/ # Servicios de negocio
│ └── general/ # Servicios base y genéricos
└── shared/ # Utilidades compartidas
- Arquitectura por capas (Controller → Service → Repository)
- Clases genéricas para operaciones CRUD comunes
- Clases base para funcionalidad compartida
- DTOs para transferencia de datos
- Mappers para conversión entre capas
Una vez que la aplicación esté ejecutándose, la documentación interactiva estará disponible en:
- Swagger UI: http://localhost:8090/swagger-ui/index.html
- OpenAPI JSON: http://localhost:8090/v3/api-docs
GET /actuator/health- Health check- Endpoints adicionales según las entidades generadas
- Driver: PostgreSQL
- Puerto por defecto: 5432
- Base de datos: simple-example-api
# Las migraciones están en: src/main/resources/database/ # Configuración en: liquibase-changelog.yml
Nota: Liquibase está deshabilitado por defecto (enabled: false). Para habilitar migraciones automáticas, cambiar a enabled: true en application.yml.
# Construir JAR ./gradlew clean build # Construir imagen docker build -t joalvarezdev/simple-example-api:latest --build-arg ARTIFACT_NAME=simple-example-api.jar .
# Construir imagen task docker-build APP_NAME=simple-example-api # Construir y subir al registry task docker-push APP_NAME=simple-example-api
docker-compose up -d
./gradlew pmdMain pmdTest
Las reglas de PMD están configuradas en linters/pmd-ruleset.xml.
./gradlew testserver.port- Puerto del servidor (por defecto: 8090)spring.datasource.*- Configuración de base de datosspringdoc.swagger-ui.*- Configuración de Swagger
# Instalar dependencias de Node (para generadores) task node # Limpiar y construir ./gradlew clean build # Ejecutar con perfil específico ./gradlew bootRun --args='--spring.profiles.active=dev' # Ver nombre del proyecto ./gradlew printProjectName